Getting started
The CloudMC API allows you to manage your environments and provision resources in a simple programmatic way using standard HTTP requests.
The API is RESTful. Responses, successful or not, are returned in JSON. Request bodies must be JSON, and should be made over SSL.
API endpoint : https://cloudmc_endpoint/api/v2
Authentication
## To authenticate, add a header
## Make sure to replace `your_api_key` with your API key.
curl "https://cloudmc_endpoint/api/v2/organizations" \
-H "MC-Api-Key: your_api_key"
API endpoints are secured by the same role-based access control (RBAC) as the CloudMC portal. To identify who is making the requests, it is required to add a header to your HTTP requests:
MC-Api-Key: your_api_key
The API key is found from the API keys section under the user profile menu. If you don't see CloudMC API keys section, contact your system administrator as you may not have the permission to see that section. Your API key carries the same privileges as your CloudMC account, so be sure to keep it secret. If you think your API has been compromised, regenerate your API key from the API keys section.
Working with sub-organizations
If you don't know what a sub-organization is, you can safely skip this section.
When using the API in an organization other than your own, make sure to specify the org_id query parameter in your request. This looks like:
https://cloudmc_endpoint/api/v2/users&org_id=:org_id
HTTP verbs
The CloudMC API can be used by any tool that is fluent in HTTP. The appropriate HTTP method should be used depending on the desired action.
| Verbs | Purpose |
|---|---|
GET |
Used to retrieve information about a resource. |
POST |
Used to create (or provision) a new resource or perform an operation on it. |
PUT |
Used to update a resource. |
DELETE |
Used to delete a resource. |
Responses
Success response
# Example without tasks
{
"data": [
{ "_comment" : "JSON representation of first object goes here" },
{ "_comment" : "JSON representation of second object goes here" }
]
}
# Example of compute API call with task
{
"taskId": "c2c13744-8610-4012-800a-0907bea110a5",
"taskStatus": "PENDING"
}
When an API request is successful, the response body will contain the data field with the result of the API call. If you're using the compute API, the data field might be empty since most of the operations are asynchronous. The response will contain the taskId and taskStatus fields so that you can retrieve the result of the operation you executed through the task API.
| Attributes | |
|---|---|
data |
The data field contains the object requested by the API caller. |
taskId |
The task id of an operation executed through the services API. |
taskStatus |
The status of a task of an operation executed the services API. |
Error response
# Example of error response
{
"errors": [
{
"code": 2012,
"message": "Cannot stop an instance that isn't in the running state",
"context": {
"id": "4534cc36-bc46-48bc-ac5c-3ee4e42f0a44",
"currentState": "Stopped",
"expectedStates": [
"Running"
],
"type": "instances"
}
}
]
}
When an API request is unsuccessful, the response body will contain the errors field :
| Attributes | |
|---|---|
errors |
A list of errors objects that contain information about each error. |
Each error has additional fields to describe it :
| Attributes | |
|---|---|
code |
The CloudMC error code. |
message |
A human readable explanation of the error code. |
context |
Additional information. |
The HTTP status codes of error responses :
| Status code | Reason |
|---|---|
200 |
The request was successful. |
204 |
The request was successful and the response body is empty. |
400 |
Bad request -- Occurs when invalid parameters are provided or when quota limit is exceeded. |
403 |
Forbidden -- Not authorized to perform this request. |
404 |
Not Found -- Cannot locate the specified endpoint. |
405 |
Method not allowed -- Cannot use that HTTP verb on the specified endpoint. |
500 |
An unexpected error occurred. |
Tasks
# Example of an asynchronus operation response
{
"taskId": "b2f82e2a-123e-4f86-a4c7-dc9b850dd11e",
"taskStatus": "PENDING"
}
Some operations take longer to execute, and to avoid blocking on the response until it is fully completed, these are treated in an asynchronous fashion. This means the API will return immediately, and provide you a taskId that is your reference to the ongoing background task. Using the tasks API, you can query the task's status to find if it has completed and obtain the result of the operation.
Retrieve a task
# Example of success response
{
"taskId": "b2f82e2a-123e-4f86-a4c7-dc9b850dd11e",
"taskStatus": "SUCCESS",
"result": {
"id": "8f064230-82a6-4f93-a17d-9cf9623b0cb5",
"name": "morty"
}
}
GET https://cloudmc_endpoint/api/v2/tasks/:id
A task has three different status: PENDING, FAILED and SUCCESS. On a successful completion of the task (i.e. it's in the SUCCESS state), the response will contain a result field which will contain the result of the operation. It is important to note that we don't persist our task, a task will only stay alive for 30 minutes (in general).
Administration
The following sections describe the various endpoints exposed by CloudMC to manage customer's configuration and interact with various core functionality of the system. Using these, you can automate various workflows without having to log into the portal, or simply integrate different aspects of CloudMC with your own toolchain.
Service connections
Service connections are the services that you can create resources for (e.g. compute, object storage). Service connections are scoped to Organizations. Thus, the relationship between a service connection and an organization can be either ownership (where the organization owns the connection) or assignation (where the connection is assigned to an organization but is owned by another) Environments are created for a specific service which allows you to create and manage resources within that service.
List service connections
GET /services/connections?organizationId=9571b279-abaf-4a37-9f39-85d1a915af7d
{
"data":[{
"id": "adfbdb51-493b-45b1-8802-3f6327afb9e6",
"serviceCode": "compute-qc",
"creationDate": "2021-12-09T21:02:16.000Z",
"name": "Compute - Québec",
"type": "CloudCA",
"status": {
"lastUpdated": "2017-08-15T12:00:00.000Z",
"reachable": true
},
"organization": {
"name": "System",
"id": "5d841eb6-5913-4244-b001-917228e7aa64"
},
"metricsEnabled": true,
"supportsQuotas": true,
"supportsPricingV2": true,
"supportsPolicies": true,
"hasWidgets": false,
"supportsUsage": true,
"supportsInfra": true,
"lastUsageRecord": "2022-03-28T18:59:59.000Z",
"quotas": [{
"name": "DefaultQuota",
"id": "081b1ebb-16c4-49e0-8120-a5b8b356b269"
},
{
"name": "CsQuota",
"id": "3734dfed-9d43-4543-ac01-bdd32875e0eb"
}],
}]
}
List service connections that are owned by a organization.
| Attributes | |
|---|---|
idUUID |
The id of the service connection. |
serviceCodestring |
The service code of the service connection. It is used in the endpoint of the services API. |
creationDatestring |
The date the service connection was created. |
namestring |
The name of the service connection. |
typestring |
The type of the service connection. |
statusObject |
Status of the service connection. Tells you if the service is up. includes: lastUpdated, reachable. |
organizationObject |
Organization that owns this service connection. includes: id, name |
metricsEnabledboolean |
Is metric collection allowed on this service connection. |
supportsQuotasboolean |
Are quotas supported on this service connection. |
supportsPricingV2boolean |
Is the V2 pricing engine supported on this service connection. |
supportsPoliciesboolean |
Are policies supported on this service connection. |
supportsUsageboolean |
Is usage collection supported on this service connection. |
supportsInfraboolean |
Is infra supported on this service connection. |
hasWidgetsboolean |
Does this service connection have widgets. |
lastUsageRecordstring |
The date which the latest usage record was recorded. |
quotasArray[object] |
The list of quota assigned to the organization. includes: id, name |
| Optional query parameters | |
|---|---|
organizationIdstring |
The organization whose connections are to be retrieved. If this is not provided then the request defaults to the user's organization. |
Retrieve a service connection
GET /services/connections/:id
{
"data":[{
"id": "adfbdb51-493b-45b1-8802-3f6327afb9e6",
"serviceCode": "compute-qc",
"creationDate": "2021-12-09T21:02:16.000Z",
"name": "Compute - Québec",
"type": "CloudCA",
"status": {
"lastUpdated": "2017-08-15T12:00:00.000Z",
"reachable": true
},
"organization": {
"name": "System",
"id": "5d841eb6-5913-4244-b001-917228e7aa64"
},
"metricsEnabled": true,
"supportsQuotas": true,
"supportsPricingV2": true,
"supportsPolicies": true,
"hasWidgets": false,
"supportsUsage": true,
"supportsInfra": true,
"lastUsageRecord": "2022-03-28T18:59:59.000Z",
"quotas": [{
"name": "DefaultQuota",
"id": "081b1ebb-16c4-49e0-8120-a5b8b356b269"
},
{
"name": "CsQuota",
"id": "3734dfed-9d43-4543-ac01-bdd32875e0eb"
}],
}]
}
Fetch a service connection.
| Attributes | |
|---|---|
idUUID |
The id of the service connection. |
serviceCodestring |
The service code of the service connection. It is used in the endpoint of the services API. |
creationDatestring |
The date the service connection was created. |
namestring |
The name of the service connection. |
typestring |
The type of the service connection. |
statusObject |
Status of the service connection. Tells you if the service is up. includes: lastUpdated, reachable. |
organizationObject |
Organization that owns this service connection. includes: id, name |
metricsEnabledboolean |
Is metric collection allowed on this service connection. |
supportsQuotasboolean |
Are quotas supported on this service connection. |
supportsPricingV2boolean |
Is the V2 pricing engine supported on this service connection. |
supportsPoliciesboolean |
Are policies supported on this service connection. |
supportsUsageboolean |
Is usage collection supported on this service connection. |
supportsInfraboolean |
Is infra supported on this service connection. |
hasWidgetsboolean |
Does this service connection have widgets. |
lastUsageRecordstring |
The date which the latest usage record was recorded. |
quotasArray[object] |
The list of quota assigned to the organization. includes: id, name |
Retrieve API credentials
GET /services/connections/:id/apiInfo
# Retrieve your API credentials
curl -X GET \
"https://cloudmc_endpoint/v1/services/connections/378442e0-d9a4-4e55-83e3-220ba1f909a8/apiInfo?environmentId=c880f6b2-f52e-40d5-b289-7211c0319ebc" \
-H "MC-Api-Key: your_api_key" \
# Response body example
{
"data": {
"canRegenerateCredentials": true,
"fields": [{
"key": "endpoint",
"value": "https://your_endpoint.com/auth",
"sensitive": false,
"environmentSpecific": false
}, {
"key": "api_key",
"value": "my_api_key",
"sensitive": true,
"environmentSpecific": false
}, {
"key": "secret_key",
"value": "my_secret_key",
"sensitive": true,
"environmentSpecific": false
}, {
"key": "project_id",
"value": "079bdead-61b5-4b38-86ed-dbbf963808ec",
"sensitive": false,
"environmentSpecific": false
}]
}
}
Retrieve your API keys for some environment within a service. A user can only access their own API keys and only for environments where they are a member.
| Query Parameters (required) | |
|---|---|
environmentIdUUID |
The id of the environment. |
| Attributes | |
|---|---|
canRegenerateCredentialsboolean |
True if the user can regenerate their API keys for the service. |
fieldsArray[object] |
An array of objects that describe the different parameters (e.g. endpoint, api_key, secret_key, project_id) comprised in the users' API credentials. includes: key, value, sensitive and environmentSpecific |
Retrieve connection parameters
GET /services/connections/:id/parameters
# Retrieve the connection parameters
curl -X GET \
"https://cloudmc_endpoint/v1/services/connections/378442e0-d9a4-4e55-83e3-220ba1f909a8/parameters" \
-H "MC-Api-key: your_api_key" \
# Response body example
{
"data": [{
"parameter": "jsonCredentials",
"id": "ee7f5ba3-3efc-4efd-819b-1dd947b3473a",
"value": "JSON representation of credentials here",
"serviceConnection": {
"id": "d461e683-30c9-4b4e-bab6-def1a3575227"
}
}, {
"parameter": "billingAccountId",
"id": "cd404ae3-884d-4b38-a9b7-cd1bba5c0a46",
"value": "02C9H96Q-2H1JS2-K9SJD8",
"serviceConnection": {
"id": "d461e683-30c9-4b4e-bab6-def1a3575227"
}
}]
}
Retrieve a service connection's parameters, used to create and manage connections to services. You can retreive these parameteres only if you are assigned a role that has the Manage Service connections permission granted to it.
| Attributes | |
|---|---|
dataArray[object] |
An array of objects that describe the service connection parameters. includes: parameter, id, value and serviceConnection.id |
Retrieve descriptor
GET /services/descriptors/:pluginType
# Retrieve service descriptor
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/descriptors/gcp/parameters"
Request body example:
{
"data": {
"type": "gcp",
"entityDescriptors": [
{
"type": "externalips",
"serviceType": "gcp",
"system": false,
"operations": {
"release": {
"name": "release",
"serviceType": "gcp",
"immediateAction": false,
"isDownload": false,
"defaultOperationType": "DELETE",
"permissionLevel": "BASE"
},
...
},
"costEstimators": [],
"viewBuilders": [
{
"serviceType": "gcp",
"view": "LIST",
"defaultView": false,
"defaultSpecificView": false
},
...
]
},
...
],
"infraEntityDescriptors": [],
"supportsInfra": false,
"supportedWidgets": [],
"hasPluginEnvironmentRoles": false,
"quotaMetricIdentifiers": [
"instance.cpu.reserved_cores",
...
],
"supportsQuota": true,
"supportsEnvironmentMetrics": false,
"supportsApiCredentials": false,
"supportsPolicies": true,
"supportsUsage": true,
"supportsPricingV2": true,
"supportsCaching": false,
"supportsMetric": true,
"metricDescriptors": [
{
"metricIdentifier": "instance.cpu.utilization",
"nameLabelKey": "metrics.instances.cpu_utilization.label",
"unitLabelKey": "metrics.instances.cpu_utilization.unit",
"entityType": "instances",
"resourceMetricType": "GAUGE"
},
...
],
"entityRelationships": {
"vpntunnels": [
{
"entityType": "networks",
"relationshipType": "PARENT"
}
],
...
},
"extensions": {
"ksdk": {}
}
}
}
| Attributes | |
|---|---|
typestring |
The type of the service descriptor. |
entityDescriptorsArray[object] |
An array of entity descriptors, each with operations, view builders and cost estimators definition. |
infraEntityDescriptorsArray[object] |
An array of entity descriptors specific to Infra. |
metricDescriptorsArray[object] |
An array of metric descriptors. |
entityRelationshipsArray[object] |
An array of relationships between entities. |
supportedWidgetsArray[string] |
An array of identifiers for supported widgets. |
quotaMetricIdentifiersArray[string] |
An array of identifiers for quota metric. |
extensionsMap |
A map of extensions for this service descriptor. |
hasPluginEnvironmentRolesboolean |
Whether or not this service descriptor has plugin environment roles. |
supportsInfraboolean |
Whether or not this service descriptor supports infra. |
supportsQuotaboolean |
Whether or not this service descriptor supports quota. |
supportsEnvironmentMetricsboolean |
Whether or not this service descriptor supports environment metrics. |
supportsApiCredentialsboolean |
Whether or not this service descriptor supports API credentials. |
supportsPoliciesboolean |
Whether or not this service descriptor supports policies. |
supportsUsageboolean |
Whether or not this service descriptor supports usage. |
supportsPricingV2boolean |
Whether or not this service descriptor supports pricing (V2). |
supportsCachingboolean |
Whether or not this service descriptor supports caching. |
This call returns a list of service descriptors which represents the metadata of a service connection.
Retrieve descriptor parameters
GET /services/descriptors/:pluginType/parameters
# Retrieve service connection parameters
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/descriptors/gcp/parameters"
Request body example:
{
"data": [
{
"field": "parentType",
"label": "gcp.service_configuration.parameters.parent_type.label",
"options": [
{
"value": "folder",
"type": "option",
"name": "gcp.service_configuration.parameters.parent_type.folder",
"is18n": true
},
{
"value": "organization",
"type": "option",
"name": "gcp.service_configuration.parameters.parent_type.organization",
"is18n": true
}
],
"required": true,
"disabled": false,
"sectionsToReload": [],
"type": "select"
},
{
"field": "parentId",
"label": "gcp.service_configuration.parameters.parent_id.label",
"descriptionLabel": "gcp.service_configuration.parameters.parent_id.description",
"required": true,
"disabled": false,
"sectionsToReload": [],
"type": "text"
},
{
"field": "jsonCredentials",
"label": "gcp.service_configuration.parameters.json_credentials.label",
"required": true,
"disabled": false,
"sectionsToReload": [],
"type": "textarea"
},
{
"field": "billingAccountId",
"label": "gcp.service_configuration.parameters.billing_account.label",
"descriptionLabel": "gcp.service_configuration.parameters.billing_account.description",
"required": true,
"disabled": false,
"sectionsToReload": [],
"type": "text"
}
]
}
| Attributes | |
|---|---|
dataArray |
An array of connection parameters, each with the following properties. |
fieldstring |
The name of connection parameter. |
typestring |
The type of the connection parameter. Possible values are text, textarea, select, checkbox. |
optionsArray[select options] |
A list of possible options for parameters of type = select |
requiredboolean |
An indication as to whether or not this parameter is a required one when creating a service connection. |
disabledboolean |
Whether or not this parameter is a disabled. |
optionsArray[string] |
A list of sections to reload when this field is modified. |
This call returns a list of parameters that must be provided (when creating a new ServiceConnection) for CloudMc to be able to successfully connect to service. While, the response includes a variety of information, the field attribute of each paramter object returned is the parameter identifier. This is used together with some value to provide the connection parameters when creating a new ServiceConnection.
Create service connection
POST /services/connections
# Create a service connection
curl -X POST "https://cloudmc_endpoint/api/v2/services/connections" \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request_body"
Request body example:
{
"name":"GCP-AmericasRegion",
"type":"gcp",
"serviceCode":"gcp-americas",
"trialEnabled": false,
"usageEnabled": false,
"metricsEnabled": false,
"commitmentTrackingEnabled": false,
"groupedParameters": [],
"dependentConnection": null,
"locations": [],
"organization": {
"id": "9571b279-abaf-4a37-9f39-85d1a915af7d"
},
"parameters":[
{
"parameter":"parentType",
"value":"folder"
},
{
"parameter":"parentId",
"value":"9123843023"
},
{
"parameter":"jsonCredentials",
"value":"<GCP-SERVICE-ACCOUNT-CREDENTIALS>"
},
{
"parameter":"billingAccountId",
"value":"141F7D-FDK3D0-F99HW2"
},
{
"parameter":"billingSubAccountsEnabled",
"value":""
},
{
"parameter":"billingDatasetName",
"value":"cmc_usage"
}
]
}
Create a new service connection in a specific organization. You will need the Reseller connections permission to execute this operation.
| Required | |
|---|---|
namestring |
The name of the new service connection. |
typestring |
The type of new service connection. (e.g. gcp, azure, aws, cloudca, swift, etc.) |
serviceCodestring |
A globally unique code that identifies this service connection. |
organizationOrganization |
The organization that the service connection should be created in. required attributes of the organization: id |
parametersArrayconnection parameters] |
An array of connection parameters specific to this connection type along with their values. This array should contain all required parameters from the list returned from the retrieve connection parameters API. required attributes per parameter: parameter, value. |
| Optional query parameters | |
|---|---|
trialEnabledstring |
Are trials allowed on this service connection. |
usageEnabledstring |
Is usage collection enabled on this service connection. |
metricsEnabledstring |
Is metric collection enabled on this service connection. |
commitmentTrackingEnabledstring |
Is commitment tracking enabled on this service connection. |
dependentConnectionobject |
The dependent connection if there is one. |
locationsArray[object] |
Locations of a service connection region. includes: name, lat and lng |
groupedParametersArray[object] |
An array of grouped connection parameters specific to this connection type along with their values. |
Test new service connection
POST /services/connections/test
# Test a new service connection
curl -X POST "https://cloudmc_endpoint/api/v2/services/connections/test" \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request_body"
Request body example:
# requires the same request body
# as outlined in the 'Create service connection' section
Test a new service connection before creating it. The request body is the same as that which is used when creating a new service connection.
Test existing service connection
POST /services/connections/:id/test
# Test a new service connection
curl -X POST "https://cloudmc_endpoint/api/v2/services/connections/9571b279-abaf-4a37-9f39-85d1a915af7d/test" \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json"
Test an existing service connection. This request does not require a body. The connection id is passed as a path parameter in the request.
Retrieve connection policy descriptors
GET /services/connections/:id/policies/descriptors
| Query Parameters | |
|---|---|
sectionstring |
The name of the policy section to load. Only the policy section matching the section name provided will return all required FormElements and the connection entity. |
# Retrieve connection policy descriptors
curl "https://cloudmc_endpoint/api/v2/services/connections/03bc22bd-adc4-46b8-988d-afddc24c0cb5/policies/descriptors?section=trials" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data":[{
"name": "general",
"label": "general",
"optional": false,
"subsection": false
},
{
"name": "trials",
"formElements": [{
"label": "cloudstack.service_configuration.policies.trials.network_config_for_trial_env.label",
"descriptionLabel": "cloudstack.service_configuration.policies.trials.network_config_for_trial_env.description",
"interpolation": {},
"options": [{
"value": "isolatedNetwork",
"type": "option",
"name": "cloudstack.service_configuration.policies.trials.network_config_for_trial_env.options.isolated_network",
"is18n": true
}, {
"value": "singleNetwork",
"type": "option",
"name": "cloudstack.service_configuration.policies.trials.network_config_for_trial_env.options.single_subnet_vpc",
"is18n": true
}],
"disabled": false,
"required": true,
"subsection": false,
"field": "trials:network_config_for_trial_envs",
"reloadOnChange": false,
"sectionsToReload": [],
"type": "select"
}],
"entity": {
"id": "7486dfbf-740d-49b1-ba68-6e4b0070ebbb",
"name": "Google Cloud Connection",
"policies": {
"version": "1.0",
"cacheEnabled": "false",
"regions": "us-east,eu-west"
}
}
}]
}
Retrieve the policy descriptors of an service connection.
| Attributes | |
|---|---|
namestring |
The name of the policy section. |
labelstring |
The label key for the policy section name. |
formElementsArray |
The FormElements returned by the policy section. Form elements are only returned for a given section if the query param section matches the name of a policy section. |
optionalboolean |
Specifies if the policy section is required or not. |
subsectionboolean |
Specifies if the policy has a subsection. |
entityObject |
The service connection entity which includes a string to string map of the ServiceConnectionPolicy::name to ServiceConnectionPolicy::value. |
Update connection policies
PUT /services/connections/:id/policies
curl -X PUT \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "[{"name": "serviceVersion", "value": "1.1"}, {"name": "cacheEnabled", "value": "true"}]" \
"https://cloudmc_endpoint/api/v2/services/connections/03bc22bd-adc4-46b8-988d-afddc24c0cb5/policies"
The above command returns a JSON structured like this:
{
"data":[
{
"id": "003c32af-e4e0-440c-871e-f20a81e6c0b7",
"name": "serviceVersion",
"value": "1.1"
},
{
"id":"a31f100a-f7c8-43d5-b64d-ee2db466f37d",
"name": "cacheEnabled",
"value": "true"
},
{
"id": "c681774a-a96c-4dff-a2a6-2e9651459de7",
"name": "regions",
"value":"us-east,eu-west"
}]
}
| Attributes | |
|---|---|
namestring |
The name of the policy. |
valuestring |
The policy value. |
List organizations assigned to a service connection
GET /services/connections/:id/assigned_organizations?organizationId=:orgId
{
"data": [
{
"id": "679fe078-a67a-4383-ab4e-51f5ef3a9287",
"name": "MyOrg",
"entryPoint": "my-org",
"state": "PROVISIONED",
"quota": {
"id": "90c3e469-71c7-4231-b27b-31dcf3a820ad",
"name": "Unlimited"
}
},
{
"id": "9571b279-abaf-4a37-9f39-85d1a915af7d",
"name": "Sysco Labs",
"entryPoint": "syscolab",
"state": "PROVISIONED",
"quota": {
"id": "66a773e8-a7e9-498b-a01d-68c8f9df2fd4",
"name": "trial"
}
},
{
"id": "d84125c6-1417-4aa3-8293-a5ddde2bfeac",
"name": "Symcentric",
"entryPoint": "symcentric",
"state": "PROVISIONED",
"quota": {
"id": "66a773e8-a7e9-498b-a01d-68c8f9df2fd4",
"name": "trial"
}
},
]
}
Returns a list of organizations to which the service connection is assigned. Only organizations that the caller has access to will be returned. Read description of the organizationId query parameter below for more details about the returned list.
| Attributes | |
|---|---|
idUUID |
The id of the organization. |
namestring |
The name of the organization. |
entryPointstring |
The entry point of the organization. Also refered to as the organization code. |
statestring |
The provisioning state of the organization on the backend service. States: PENDING, PROVISIONING, PROVISIONED, PENDING_PURGE, PURGING, PURGED. |
quotaObject |
The quota assigned to the organization (may be null depending on if the connection supports quotas or not). includes: id, name |
| Optional query parameters | |
|---|---|
organizationIdstring |
The organization from whose scope the request is being made. Based on this the returned list may vary. Organizations that are above this organization (represented by the id) in the organization tree hierarchy will be filtered from the returned list even if they have the connection assigned to them. If this is not provided then the request defaults to the user's organization. |
Organizations
Organizations are the largest logical grouping of users, environments and resources available in CloudMC. Each organization is isolated from other organizations. It has its own subdomain ([entryPoint].CloudMC) and is protected by its own customizable system roles. An administrator that must manage its sub-organizations environments or provisioned resources can do so by having the Access other levels permission. Additionally, provisioned resource usage is metered at the organization level facilitating cost tracking.
List organizations
GET /organizations
Retrieves a list of organizations visible to the caller. In most cases, only the caller's organization will be returned. However if the caller's organization has sub-organizations, and the caller has the Access other levels permission, the sub-organizations will be returned as well.
# Retrieve visible organizations
curl "https://cloudmc_endpoint/api/v2/organizations" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "03bc22bd-adc4-46b8-988d-afddc24c0cb5",
"lineage": "03bc22bd-adc4-46b8-988d-afddc24c0cb5, 5ff3a3d8-41a8-4ca2-813f-7d5af4cfc872",
"name": "Umbrella Corporation",
"entryPoint": "umbrella",
"billableStartDate": "2017-08-15T12:00:00.000Z",
"creationDate": "2022-04-29T19:49:18.000Z",
"isBillable": true,
"billingMode": "CREDIT_CARD",
"isReseller": false,
"features": [],
"customFields": {},
"tags": [
{
"system": true,
"name": "billable",
"id": "5a84485f-7eed-11ec-b819-0242ac120002"
},
{
"system": false,
"name": "organizationTagOne",
"id": "fc2a164f-3871-4eed-9591-d3ceb838550b"
},
{
"system": false,
"name": "organizationTagTwo",
"id": "12d6d802-ca56-4c22-9c9d-e76ee0b1e97c"
}
],
"deleted": false,
"isDbAuthentication": true,
"isLdapAuthentication": false,
"isTrial": false,
"reseller": {
"id": "5d841eb6-5913-4244-b001-917228e7aa64"
},
"parent": {
"id": "8e3393ce-ee63-4f32-9e0f-7b0200fa655a",
"name": "Capcom"
},
"environments": [
{
"id": "9df14056-51e2-4000-ab14-beeaa488500d",
"deleted": false
}
],
"serviceConnections":[
{
"id":"11607a49-9691-40fe-8022-2e148bc0d720",
"serviceCode":"compute-qc",
"state": "PROVISIONED",
}
],
"users": [
{
"id":"0c3ffcce-a98d-4159-b6fc-04edd34e89b7",
"userName":"wbirkin",
"deleted": false
}
]
}
]
}
| Optional Query Parameters | |
|---|---|
include_deletedboolean |
Whether or not to include deleted organizations and resources in the response. |
| Attributes | |
|---|---|
idUUID |
The id of the organization. |
lineagestring |
A string of comma-seperated UUIDs of the lineage of the organization. |
namestring |
The name of the organization. |
entryPointstring |
The entry point of the organization is the subdomain of the organization in the CloudMC URL : [entryPoint].CloudMC. |
billableStartDatestring |
The billable start date in ISO 8601 of the organization. |
creationDatestring |
The date the organization was created in ISO 8601. |
isBillableboolean |
If the organization is billable this values is true, false otherwise. |
billingModeenum |
The billing mode of the organization. It could be either "MANUAL" or "CREDIT_CARD". Default value is "MANUAL". |
tagsArray[object] |
Tags associated to the organization. includes: idUUID, namestring, systemboolean |
parentOrganization |
If the organization is a sub-organization, it will have its parent organization. includes:id,name. |
resellerOrganization |
The nearest reseller of the organization. includes:id. |
environmentsArray[Environment] |
The environments belonging to the organization. includes: id |
serviceConnectionsArray[ServiceConnection] |
The services for which the organization is allowed to provision resources. includes: id,serviceCode |
resourceCommitmentsArray[ResourceCommitment] |
The resource commitments applied on the organization. |
usersArray[User] |
The users of the organization. includes: id |
featuresArray[[OrganizationFeature]] |
The features offered by the organization and their access levels. |
customFieldsmap |
Map of custom fields on the organization and their values. |
isDbAuthenticationboolean |
Whether or not the organization supports database authentication. |
isLdapAuthenticationboolean |
Whether or not LDAP authentication is enabled on this organization. |
isTrialboolean |
Whether or not this is a trial organization. |
isResellerboolean |
Whether or not this organization is a reseller or not. |
customDomainVerifiedDomain |
The custom domain for the organization. |
Retrieve an organization
GET /organizations/:id
Retrieve an organization's details.
# Retrieve an organization
curl "https://cloudmc_endpoint/api/v2/organizations/03bc22bd-adc4-46b8-988d-afddc24c0cb5" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": {
"id": "03bc22bd-adc4-46b8-988d-afddc24c0cb5",
"lineage": "03bc22bd-adc4-46b8-988d-afddc24c0cb5, 5ff3a3d8-41a8-4ca2-813f-7d5af4cfc872",
"name": "Nintendo US",
"entryPoint": "nintendo-us",
"billableStartDate": "2017-08-15T12:00:00.000Z",
"isBillable": true,
"billingMode": "CREDIT_CARD",
"isReseller": false,
"tags": [
{
"system": true,
"name": "billable",
"id": "5a84485f-7eed-11ec-b819-0242ac120002"
},
{
"system": false,
"name": "organizationTagOne",
"id": "fc2a164f-3871-4eed-9591-d3ceb838550b"
},
{
"system": false,
"name": "organizationTagTwo",
"id": "12d6d802-ca56-4c22-9c9d-e76ee0b1e97c"
}
],
"parent": {
"id": "8e3393ce-ee63-4f32-9e0f-7b0200fa655a",
"name": "Nintendo"
},
"reseller": {
"id": "5d841eb6-5913-4244-b001-917228e7aa64"
},
"customFields": {},
"notes": "",
"customFieldDefinitions": [],
"isDbAuthentication": true,
"isLdapAuthentication": false,
"quotas": [
{
"name": "unlimited",
"id": "3311d69e-12c8-4295-bae0-34e9a1c57982",
"serviceConnection": {
"id": "78f55cd7-47c9-47ac-a6a0-203b838d1507"
}
}
],
"ldap": {
"deleted": false,
"id": "4de3ed48-0b9c-43c8-a93a-244d763b6861"
},
"environments": [
{
"id": "9df14056-51e2-4000-ab14-beeaa488500d"
}
],
"serviceConnections": [
{
"id":"11607a49-9691-40fe-8022-2e148bc0d720",
"serviceCode":"compute-qc",
"state": "PROVISIONED",
}
],
"users": [
{
"id":"0c3ffcce-a98d-4159-b6fc-04edd34e89b7",
"userName":"reggie"
}
]
}
}
| Attributes | |
|---|---|
idUUID |
The id of the organization. |
lineagestring |
A string of comma-seperated UUIDs of the lineage of the organization. |
namestring |
The name of the organization. |
entryPointstring |
The entry point of the organization is the subdomain of the organization in the CloudMC URL :[entryPoint].CloudMC. |
billableStartDatestring |
The billable start date in ISO 8601 of the organization. |
isBillableboolean |
If the organization is billable this values is true, false otherwise. |
quotasArray[Quotas] |
A list of quotas that associated to the organization. |
billingModeenum |
The billing mode of the organization. It could be either "MANUAL" or "CREDIT_CARD". Default value is "MANUAL". |
tagsArray[object] |
Tags associated to the organization. includes: idUUID, namestring, systemboolean |
parentOrganization |
If the organization is a sub-organization, it will have its parent organization. includes:id,name. |
resellerOrganization |
The nearest reseller of the organization. includes:id. |
environmentsArray[Environment] |
The environments belonging to the organization. includes: id |
serviceConnectionsArray[ServiceConnection] |
The services for which the organization is allowed to provision resources. includes: id,serviceCode |
resourceCommitmentsArray[ResourceCommitment] |
The resource commitments applied on the organization. |
usersArray[User] |
The users of the organization. includes: id |
notesstring |
Organization notes. |
featuresArray[[OrganizationFeature]] |
The features offered by the organization and their access levels. |
customFieldsmap |
Map of custom fields on the organization and their values. |
customFieldDefinitionsArray[[CustomFieldDefinition]] |
Custom field definitions of the organization. |
isDbAuthenticationboolean |
Whether or not the organization supports database authentication. |
isLdapAuthenticationboolean |
Whether or not LDAP authentication is enabled on this organization. |
ldapObject |
LDAP authentication associated with the organization. |
isTrialboolean |
Whether or not this is a trial organization. |
isResellerboolean |
Whether or not this organization is a reseller or not. |
customDomainVerifiedDomain |
The custom domain for the organization. |
Create organization
POST /organizations
Creates a new organization as a sub-organization of the caller's organization, or a sub-organization of the specified parent or at the top level if the calling user has an unscoped permission. The caller requires the Organizations create permission.
Any service connections that are supplied in the request will be assigned to the organization asynchronously. The state of the connections assigned to the organization and its progress is reflected in the organization service connections.
The task id returned in the response below can also be used to track the completion of the asynchronous assignation of connections to this organization.
# Create an organization
curl -X POST "https://cloudmc_endpoint/api/v2/organizations" \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request_body"
Request body example:
{
"entryPoint":"umbrella",
"name":"Umbrella Corp",
"serviceConnections":[
{
"id":"9acb3b76-d5d0-420c-b075-ef320b7e5a3e"
}
],
"parent" : {
"id":"bc0ceecf-feb5-412c-ab6e-a8df8eb7fbbd"
}
}
| Required | |
|---|---|
namestring |
The name of the organization. Must be between 2 and 50 (inclusive) and the first character must be alphanumeric. |
entryPointstring |
The entry point of the organization is the subdomain of the organization in the CloudMC URL : [entryPoint].CloudMC. |
| Optional | |
|---|---|
serviceConnectionsArray[ServiceConnection] |
A list of service connections for which the organization may provision resources. required : id |
parentOrganization |
The organization that will be the parent of the new organization. By default, it will default to the caller's organization. required : id |
billingModeenum |
The billing mode of the organization. It could be either "MANUAL" or "CREDIT_CARD". Default value is "MANUAL". |
tagsArray[object] |
Tags associated to the organization. Tags provided in the request cannot be system tags. required : id or name |
The responses' data field contains the created organization with its id.
| Response | |
|---|---|
dataOrganization |
The information about the created organization |
# Response body example
{
"taskId": "aee1862d-c187-43eb-be12-754c24022dfc",
"taskStatus": "PENDING",
"data": {
"lineage": "85487519-54e3-4dad-9c42-3a5ff7f1a359",
"quotas": [
{
"name": "Unlimited",
"id": "09244b06-5b89-43fe-b972-016a590eeb38",
"serviceConnection": {
"id": "8901494c-01ee-4d6b-bd12-cd5347127039"
}
}
],
"hashAlgorithmName": "SHA-512",
"hashIterations": 100,
"isTrial": false,
"creationDate": "2020-04-14T18:46:15.000Z",
"tags": [],
"isDbAuthentication": true,
"deleted": false,
"serviceConnections": [],
"reseller": {
"id": "5d841eb6-5913-4244-b001-917228e7aa64"
},
"ldap": {
"deleted": false,
"id": "0bf68b3a-8248-487b-a855-1003874339e7"
},
"name": "Shopify",
"id": "85487519-54e3-4dad-9c42-3a5ff7f1a359",
"entryPoint": "shopify"
}
}
Update organization
PUT /organizations/:id
Update an organization. It's parent organization cannot be changed. Any service connections that are supplied in the request will be assigned to the organization asynchronously. The state of the connections assigned to the organization and its progress is reflected in the organization service connections.
The task id returned in the response below can also be used to track the completion of the asynchronous assignation of connections to this organization.
# Update an organization
curl -X PUT "https://cloudmc_endpoint/api/v2/organizations/03bc22bd-adc4-46b8-988d-afddc24c0cb5" \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request_body"
Request body example:
{
"entryPoint":"umbrella",
"name":"Umbrella Corp",
"serviceConnections":[
{
"id":"9acb3b76-d5d0-420c-b075-ef320b7e5a3e"
}
]
}
| Optional | |
|---|---|
namestring |
The name of the organization. Must be between 2 and 50 (inclusive) and the first character must be alphanumeric. |
entryPointstring |
The entry point of the organization is the subdomain of the organization in the CloudMC URL : [entryPoint].CloudMC. |
serviceConnectionsArray[ServiceConnection] |
A list of service connections for which the organization may provision resources. The caller must have access to all connections that are provided. Read below (after the request parameter list) for more details. required attributes of the service connection: id |
tagsArray[object] |
Tags associated to the organization. Tags provided in the request cannot be system tags. Must have the Reseller: Organizations metadata: Manage permission. User cannot modify tags of their own (non-root) organization. required : id or name |
resourceCommitmentsArray[ResourceCommitment] |
The resource commitments applied on the organization. |
usersArray[User] |
The users of the organization. required attributes of the organization : id |
notesstring |
Organization notes. Must have the Organization metadata: Manage permission. |
isDbAuthenticationboolean |
Whether or not the organization supports database authentication. |
isLdapAuthenticationboolean |
Whether or not LDAP authentication is enabled on this organization. |
customDomainVerifiedDomain |
An object describing a verified domain. Must have the Organization: Manage reseller features permission. required : id |
billingModeenum |
The billing mode of the organization. It could be either "MANUAL" or "CREDIT_CARD". Default value is "MANUAL". |
isBillableboolean |
If the organization is billable this values is true, false otherwise. |
The responses' data field contains the updated organization.
NB : At this time the API only enables adding access to Service connections but not revoking it. A Service connection can be assigned to an organization only if:
- The organization owns the service connection (i.e. the organizationId of the service connection is this organization's id)
- If the organization is a sub-organization in some organization hierachy, then the service connection must be either owned by or assigned to its immediate parent organization
Response |
data
Organization | The information about the updated organization
# Response body example
{
"data": {
"lineage": "85487519-54e3-4dad-9c42-3a5ff7f1a359",
"quotas": [
{
"name": "Unlimited",
"id": "09244b06-5b89-43fe-b972-016a590eeb38",
"serviceConnection": {
"id": "8901494c-01ee-4d6b-bd12-cd5347127039"
}
}
],
"isTrial": false,
"creationDate": "2020-04-14T18:46:15.000Z",
"tags": [],
"isDbAuthentication": true,
"deleted": false,
"serviceConnections": [],
"ldap": {
"deleted": false,
"id": "0bf68b3a-8248-487b-a855-1003874339e7"
},
"name": "Shopify",
"id": "85487519-54e3-4dad-9c42-3a5ff7f1a359",
"entryPoint": "shopify"
},
"taskId": "aee1862d-c187-43eb-be12-754c24022dfc",
"taskStatus": "PENDING"
}
Delete organization
DELETE /organizations/:id
Delete an organization. The caller may not delete his own organization. Also, an organization may not be deleted if it has sub-organizations.
Organizations are deleted asynchronously on the underlying services.
Deleting an organization is composed of the following steps:
- Remove users from environments
- Delete users
- Delete environments
- Delete organization
These steps are performed on each service assigned to the organization.
If one of the steps fails, subsequent steps are aborted and an error response is returned.
Following an error response, subsequent delete attempts will be considered as a "force delete". A force delete entails reattempting to delete the organization as explained above and then deleting related database models regardless of the response from the underlying services.
# Delete an organization
curl -X DELETE "https://cloudmc_endpoint/api/v2/organizations/03bc22bd-adc4-46b8-988d-afddc24c0cb5" \
-H "MC-Api-Key: your_api_key"
| Response | |
|---|---|
taskIdUUID |
The id of the task. |
taskStatusstring |
The status of the task. |
# Response body example
{
"taskId": "cd921b44-ca9f-4f6b-b184-f952e5ab010a",
"taskStatus": "PENDING"
}
Returns an HTTP status code 204, with an empty response body.
Get verified domains
GET /organizations/:organization_id/verified_domains
Get a list of all verified domains on the specified organization.
# Retrieve all verified domains
curl "https://cloudmc_endpoint/api/v2/organizations/87895f43-51c1-43cc-b987-7e301bf5b86a/verified_domains" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": [
{
"lastCheckedDate": "2020-07-31T19:14:36Z",
"createdDate": "2020-07-31T19:12:55Z",
"domain": "aGoodFakeDomain.com",
"organization": {
"name": "my organization",
"id": "87895f43-51c1-43cc-b987-7e301bf5b86a",
"entryPoint": "myOrg"
},
"id": "22d30872-8e90-43b5-b1ba-636bead42e34",
"verificationCode": "cmc-verification=81405f20-f96e-4964-b8bb-fb97c802ca5c",
"status": "VERIFIED"
},
{
"lastCheckedDate": "2020-08-03T15:24:35Z",
"createdDate": "2020-08-03T14:41:20Z",
"domain": "anotherFakeDomain.com",
"organization": {
"name": "my organization",
"id": "87895f43-51c1-43cc-b987-7e301bf5b86a",
"entryPoint": "myOrg"
},
"id": "5752811e-08cf-4105-91ca-bac80efe3d23",
"verificationCode": "cmc-verification=a571fb45-1dc6-4569-adf2-9e166861499f",
"status": "PENDING"
}
]
}
| Attributes | |
|---|---|
lastCheckedDatestring |
The last date that the domain's DNS was checked for the TXT record with the verification code. In ISO 8601. |
createdDatestring |
The date the verified domain was created. In ISO 8601. |
domainstring |
The domain associated with the organization. |
organizationOrganization |
The organization to which the verified domain belongs. includes:id,name, entryPoint. |
idUUID |
The id of the verified domain. |
verificationCodestring |
The verification code for the domain. This is the value that should be added to the domain's DNS registration as a new TXT record. CloudMC will check on a recurring schedule if the TXT record has been added to the domain, and update the status to VERIFIED once found. |
statusstring |
The status of the domain ownership proof. Possible values are : VERIFIED, PENDING, ERROR. |
Create verified domain
POST /organizations/:organization_id/verified_domains
Creates a new verified domain in the specified organization.
# Create a verified domain
curl -X POST "https://cloudmc_endpoint/api/v2/organizations87895f43-51c1-43cc-b987-7e301bf5b86a/verified_domains" \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request_body"
Request body example:
{
"domain":"www.umbrellaCorp.com"
}
| Required | |
|---|---|
domainstring |
The domain associated with the organization. |
The responses' data field contains the created verified domain with its id, as well as with the verificationCode. A TXT record will need to be added to the domain's DNS registration with the verification code as its value.
Delete verified domain
DELETE /organizations/:organization_id/verified_domains/:id
Delete a specified domain on the organization.
# Delete a verified domain
curl -X DELETE "https://cloudmc_endpoint/api/v2/organizations/03bc22bd-adc4-46b8-988d-afddc24c0cb5/verified_domains/22d30872-8e90-43b5-b1ba-636bead42e34" \
-H "MC-Api-Key: your_api_key"
Returns an HTTP status code 200, with an empty response body.
Get security settings
GET /organizations/organization_id/security_settings
Retrieve the security settings for the organization.
# Retrieve the organization's security settings
curl "https://cloudmc_endpoint/api/v2/organizations/87895f43-51c1-43cc-b987-7e301bf5b86a/security_settings" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": {
"defaultRole": {
"name": "guest",
"id": "6e022506-ab89-4676-859d-06d370b67417"
},
"organization": {
"name": "my organization",
"id": "87895f43-51c1-43cc-b987-7e301bf5b86a",
"entryPoint": "myOrg"
},
"autoCreationEnabled": true,
"blockedNativeLoginDomain": "",
"verifiedDomains": [
{
"lastCheckedDate": "2020-08-03T17:19:36Z",
"createdDate": "2020-08-03T16:14:00Z",
"domain": "newDomainName.com",
"organization": {
"lineage": "87895f43-51c1-43cc-b987-7e301bf5b86a",
"notes": "",
"isTrial": false,
"creationDate": "2020-04-30T21:25:49.000Z",
"isLdapAuthentication": false,
"isBillable": false,
"isDbAuthentication": true,
"deleted": false,
"ldap": {
"id": "063ec8ee-8a55-4374-9c8c-57a10f11cf1b"
},
"name": "my organization",
"id": "87895f43-51c1-43cc-b987-7e301bf5b86a",
"entryPoint": "myOrg"
},
"id": "29d66b1d-669a-439b-883a-d7c1e36e1ca6",
"verificationCode": "cmc-verification=8c8f5473-9306-4e16-a820-a747482e85e5",
"status": "VERIFIED"
}
],
"passwordPolicy": {
"constraints": [
{
"name": "min_password_length",
"value": 8,
"isMandatory": false
},
{
"name": "min_lowercase_letters",
"value": 1,
"isMandatory": true
},
{
"name": "min_uppercase_letters",
"value": 1,
"isMandatory": true
},
{
"name": "min_numbers",
"value": 1,
"isMandatory": true
},
{
"name": "min_special_characters",
"value": 1,
"isMandatory": true
}
],
"isParentPolicy": false,
}
}
}
| Attributes | |
|---|---|
defaultRoleobject |
The role that will be assigned to new users logging into the organization with an email domain matching that of the organization's security settings. |
defaultRole.namestring |
The name of the default role. |
defaultRole.idUUID |
The id of the default role. |
organizationOrganization |
The organization to which the verified domain belongs. includes:id,name, entryPoint. |
autoCreationEnabledboolean |
A boolean specifying whether to enable automatic end-user account creation upon successful OIDC login. |
blockedNativeLoginDomainstring |
The blocked native login domain. |
verifiedDomainsArray[verified domains] |
A list of verified domains (with VERIFIED status) for which successful matching OIDC logins will create new users. |
passwordPolicyobject |
The password policy assigned to the organization. |
passwordPolicy.constraintsArray[Object] |
List of password policy constraints. |
passwordPolicy.isParentPolicyboolean |
A boolean flag to indicate if the password policy is a parent policy. |
passwordPolicy.constraints.namestring |
A string that represents the constraint name. |
passwordPolicy.constraints.valueint |
An integer that represents the minimum value for the constraint. |
passwordPolicy.constraints.isMandatoryboolean |
A boolean flag to indicate if the constraint is mandatory or not. |
Update security settings
PUT /organizations/:organization_id/security_settings
# Update an organization's security settings
curl -X PUT "https://cloudmc_endpoint/api/v2/organizations/03bc22bd-adc4-46b8-988d-afddc24c0cb5/security_settings" \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request_body"
Request body example:
{
"autoCreationEnabled": true,
"verifiedDomains": [
{
"id": "29d66b1d-669a-439b-883a-d7c1e36e1ca6"
}
],
"defaultRole": {
"name": "guest",
"id": "6e022506-ab89-4676-859d-06d370b67417"
},
"passwordPolicy": {
"constraints": [
{
"name": "min_password_length",
"value": 8,
"isMandatory": false
},
{
"name": "min_lowercase_letters",
"value": 1,
"isMandatory": true
},
{
"name": "min_uppercase_letters",
"value": 1,
"isMandatory": true
},
{
"name": "min_numbers",
"value": 1,
"isMandatory": true
},
{
"name": "min_special_characters",
"value": 1,
"isMandatory": true
}
]
}
}
Create a new or update an existing security settings for an organization.
| Required | |
|---|---|
defaultRoleobject |
The role that will be assigned to new users logging into the organization with an email domain matching that of the organization's security settings. |
defaultRole.namestring |
The name of the default role. |
defaultRole.idUUID |
The id of the default role. |
| Optional | |
|---|---|
autoCreationEnabledboolean |
A boolean specifying whether to enable automatic end-user account creation upon successful OIDC login. |
verifiedDomainsArray[verified domains] |
A list of objects containing the ids of verified domains (with VERIFIED status) for which successful matching OIDC logins will create new users. |
blockedNativeLoginDomainstring |
The blocked native login domain. |
passwordPolicyobject |
The password policy that will be assigned to the organization. |
passwordPolicy.constraintsArray[Object] |
List of password policy constraints objects with the following fields. |
passwordPolicy.constraints.namestring |
A string that represents the constraint name. |
passwordPolicy.constraints.valueint |
An integer that represents the minimum value for the constraint. |
passwordPolicy.constraints.isMandatoryboolean |
A boolean flag to indicate if the constraint is mandatory or not. |
Returns an HTTP status code 200, with an empty response body.
- If
defaultRoleis not passed in the request:- The system will assign
Guestas a default role to the organization.
- The system will assign
- If
passwordPolicyis passed in the request:- The system will create a new or update the existing password policy for the organization.
- If
autoCreationEnabledand/orverifiedDomainsis passed in the request:- The system will create a new or update the existing security settings for the organization.
Get password policy
GET /organizations/organization_id/password_policy
Retrieve the password policy for the organization.
# Retrieve the organization's own or inherited password policy.
curl "https://cloudmc_endpoint/api/v2=2/organizations/e8d95716-26a9-4054-833e-81cd3a5155cd/password_policy" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": [
{
"name": "min_password_length",
"value": 8,
"isMandatory": true
},
{
"name": "min_lowercase_letters",
"value": 1,
"isMandatory": true
},
{
"name": "min_uppercase_letters",
"value": 1,
"isMandatory": true
},
{
"name": "min_numbers",
"value": 1,
"isMandatory": true
},
{
"name": "min_special_characters",
"value": 1,
"isMandatory": true
}
]
}
| Attributes | |
|---|---|
| Array[Object] | A list of password policy constraint objects with the following fields. |
namestring |
The name of the constraint. |
valueint |
The minimum value for the constraint. |
isMandatoryboolean |
Flag to indicate if the constraint is mandatory or not. |
Delete password policy
DELETE /organizations/:id/password_policy
Delete a password policy for an organization. Root reseller organization will not be able to delete its password policy. A reseller sub-organization can delete its password policy.
# Delete an organization
curl -X DELETE "https://cloudmc_endpoint/api/v2/organizations/e8d95716-26a9-4054-833e-81cd3a5155cd/password_policy" \
-H "MC-Api-Key: your_api_key"
Returns an HTTP status code 200, with an empty response body.
Get manageable connections of an organization
GET /organizations/:id/manageable_connections
Get a list of Service connections that can be managed by the current user on the given organization.
# Update an organization
curl -X GET "https://cloudmc_endpoint/api/v2/organizations/03bc22bd-adc4-46b8-988d-afddc24c0cb5/manageable_connections" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
[
{
"id": "2f7b4d49-b426-424f-b272-396b66947bb1",
"name": "Microsoft Azure",
"type": "azure",
"serviceCode": "azure-dev",
"status": {
"id": "97b3f5fa-1bda-4dae-b716-8039d9b89a56",
"serviceConnection": null,
"reachable": true,
"lastUpdated": null,
"message": null,
},
"quotas": []
},
{
"id": "b1dc9202-4e1a-4180-9ed6-28025b5aacdd",
"name": "Objects Lab",
"type": "swiftstack",
"serviceCode": "objects-lab",
"iconOverrideUrl": "https://icon-override-url.png",
"status": {
"id": "74a78d2b-c0da-475e-9bb7-218adc745d81",
"serviceConnection": null,
"reachable": true,
"lastUpdated": null,
"message": null,
},
"quotas": [
{ ... },
{ ... },
]
}
]
| Attributes | |
|---|---|
idstring |
The id of the service connection. |
namestring |
The name of the service connection. |
typestring |
The type of the service connection. (e.g. gcp, azure, aws, cloudca, swift, etc.) |
serviceCodestring |
The globally unique serviceCode that identifies the service connection. |
statusObject |
The status object describing the status of connectivity to this service from CloudMc. |
quotasArray[Quotas] |
A list of quotas that can be associated to the service connnection. |
iconOverrideUrlstring |
The icon the overwrites the default icon for the service connection. |
The user should have Connections reseller permission on the organization. This list includes the following types of Service connections:
- If the API user is from this organization:
- Service connections
owned byandassigned tothis organization
- Service connections
- If the API user is from this organization's immediate parent organization:
- Service connections
assigned tothis organization - Service connections
owned byandassigned tothis organization's immediate parent organization (i.e. the user's organization)
- Service connections
- If the API user is from any organization between this organization's immediate parent organization and the root organization:
- Service connections
assigned tothis organization - Service connections
owned bythe user's organization and isassigned tothis organization's immediate parent organization - Service connections
assigned tothe user's organization and isassigned tothis organization's immediate parent organization
- Service connections
Mark organization as reseller
POST /organizations/:organization_id/mark_reseller
# Mark an organization as reseller
curl -X POST "https://cloudmc_endpoint/api/v2/organizations/03bc22bd-adc4-46b8-988d-afddc24c0cb5/mark_reseller" \
-H "MC-Api-Key: your_api_key" \
Mark the organization as a reseller. Returns an HTTP status code 200, with an empty response body.
Get identity providers
GET /organizations/:organization_id/identity_providers
Retrieve the identity providers for the organization.
# Retrieve the organization's identity providers
curl "https://cloudmc_endpoint/api/v2/organizations/87895f43-51c1-43cc-b987-7e301bf5b86a/identity_providers" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "32a5640c-b366-44b1-882a-ee2e1951c592",
"organization": {
"name": "my organization",
"id": "87895f43-51c1-43cc-b987-7e301bf5b86a",
"entryPoint": "myOrg"
},
"type": "OIDC",
"css": "",
"provider": "GOOGLE",
"displayName": "Google",
"logo": "/static/img/google_signin.svg",
"rank": 1
}
]
}
| Attributes | |
|---|---|
idUUID |
The id of the identity provider. |
organizationOrganization |
The organization to which the verified domain belongs. includes:id,name, entryPoint. |
typestring |
The type of authentication protocol. Possible values: OIDC, SAML. |
cssstring |
Custom css for the login button of the identity provider. |
providerstring |
The name of the provider. Possible values include the default providers (e.g GOOGLE), or CUSTOM for a custom user-defined provider. |
displayNamestring |
The display name of the identity provider that will appear on the login screen. |
logostring |
A base64 encoded data URL or URL to an image for the logo to display on the login screen. |
rankint |
If provided, this integer sorts identity providers on the Login page in ascending order. |
Get billing information
GET /organizations/:organization_id/billing_info
Retrieve the billing information for an organization.
# Retrieve the organization's billing information
curl "https://cloudmc_endpoint/api/v2/organizations/87895f43-51c1-43cc-b987-7e301bf5b86a/billing_info" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": {
"id": "23910576-d29f-4c14-b663-31d728ff49a5",
"organization": {
"id": "23910576-d29f-4c14-b663-31d728ff49a5"
},
"billingProvider": {
"id": "f26e66a4-755c-4867-b565-ad68aa515237"
},
"cardType": "Mastercard",
"cardMaskedNumber": "************1234",
"cardName": "John Doe",
"cardExp": "0124",
"billingAddressLineOne": "555 SomeStree",
"billingAddressLineTwo": "App #2",
"billingAddressCity": "SomeCity",
"billingAddressProvince": "NY",
"billingAddressPostalCode": "555555",
"billingAddressCountry": "US",
"customAttribute" : {
"uid": "774B145528524D7C65590CE77B933135",
"customerRefNumber": "208523664"
}
}
}
| Attributes | |
|---|---|
idUUID |
The id of the billing information. |
organizationOrganization |
The organization to which belongs the billing information. |
billingProviderBillingProvier |
The billing provider associated to the credit card. |
cardTypestring |
The credit card type. |
cardMaskedNumberstring |
The credit card masked number. |
cardNamestring |
The name on the credit card |
cardExpstring |
The credit card expiration ('mmyy' format) |
billingAddressLineOnestring |
The address line 1 of the billing address. |
billingAddressLineTwostring |
The address line 2 of the billing address. |
billingAddressCitystring |
The city of the billing address. |
billingAddressProvincestring |
The province or state code (2 letters) of the billing address. |
billingAddressPostalCodestring |
The postal/zip code of the billing address. |
billingAddressCountrystring |
The country code (ISO 2 or 3 letter code) of the billing address. |
customAttribute Object |
The custom attributes associated to the billing provider |
| Chase attributes | |
|---|---|
customAttribute.uid string |
Chase registration id. |
customAttribute.customerRefNum string |
Chase customer reference number/profile id. |
customAttribute.originalMitTransactionId string |
Chase customer original transaction id. |
Clear credit card information
DELETE /organizations/:organization_id/billing_info
Delete the billing information for an organization. Only accessible to users with System:Pricings permission.
Returns an HTTP status code 200, with an empty response body.
# Delete the organization's billing information
curl -X DELETE "https://cloudmc_endpoint/api/v2/organizations/87895f43-51c1-43cc-b987-7e301bf5b86a/billing_info" \
-H "MC-Api-Key: your_api_key"
Set billable organization information
PUT /organizations/:organization_id/billable
Set the organization to billable and update the billable organization information. If the organization's assigned pricing package is changed, this API will reprocess usage starting from the current in progres billing cycle. Any previously drafted invoices will be generated and reports will reflect the pricing configuration of the newly selected pricing package.
# Update billable organization info
curl -X PUT "https://cloudmc_endpoint/api/v2/organizations/87895f43-51c1-43cc-b987-7e301bf5b86a/billable" \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request_body"
Request body example:
{
"id": "39f6260d-f0ca-4be9-93c4-46405d471c04",
"billableStart": "2015-01-18",
"pricingPackage": {
"id": "58bad1de-1f87-422b-b44f-27ed58889272"
}
}
| Required | |
|---|---|
idUUID |
The id of the udpated billable organization information. |
billableStartstring |
The date the organization became billable, in YYYY-MM-DD format. |
pricingPackage.idUUID |
The id of the pricing package applied on the organization. |
| Optional | |
|---|---|
billableEndstring |
The date the organization stops being billable, in YYYY-MM-DD format. |
The response's data field contains the updated billable organization info with it's id, the billableStart, as well as the pricing package and it'sid.
List applicable pricing packages to an organization
GET /organizations/:organization_id/pricing_packages
Retrieves a list of applicable pricing packages to an organization.
# Retrieve visible organizations
curl "https://cloudmc_endpoint/api/v2/organizations/87895f43-51c1-43cc-b987-7e301bf5b86a/pricing_packages" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": [
{
"offerType": "30-day-trial",
"pricingDefinition": {
"id": "c9a396f1-690a-4201-a3bf-b1da37221acc"
},
"endDate": "2022-09-14T00:00:00Z",
"organization": {
"id": "de6cf332-14b2-4da8-8522-3dfe12fcd0da"
},
"name": {
"en": "Pricing Package",
"fr": "Pricing Package"
},
"id": "92041aa8-7784-45b0-aa85-76376ede784d",
"creationDate": "2021-09-13T15:18:38.000Z",
"startDate": "2021-09-22T20:09:32.084Z"
}
]
}
| Attributes | |
|---|---|
idUUID |
The UUID of the pricing package. |
offerTypestring |
The offer type of the pricing package. |
pricingDefinitionObject |
The pricing definition associated with the pricing package. |
pricingDefinition.idUUID |
The UUID of the pricing. |
organizationObject |
The object representing the organization owning the pricing package. |
organization.idUUID |
The UUID of the organization. |
startDatedate |
The start date of the pricing package. |
endDatedate |
The end date of the pricing package. If it is not present, there is no end date defined. |
creationDateObject |
The date the pricing package was created. |
name Map[String, String] |
The name translations of the pricing package. |
List billing emails
GET /organizations/:organization_id/billing_emails
Retrieves a list of billing emails configured on the org. These emails will also receive billing related emails along with users that have the Admin:Billing role.
# Retrieve billing emails
curl "https://cloudmc_endpoint/api/v2/organizations/87895f43-51c1-43cc-b987-7e301bf5b86a/billing_emails" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": {
"billingEmails": {
"example@email.com": "John",
"billing@company.com": "Billing team"
}
}
}
| Attributes | |
|---|---|
billingEmailsmap |
A map of billing emails and names associated with them. |
Update billing emails
PUT /organizations/:organization_id/billing_emails
Update the list of billing emails configured on the org. These emails will also receive billing related emails along with users that have the Admin:Billing role.
# Update billing emails
curl "https://cloudmc_endpoint/api/v2/organizations/87895f43-51c1-43cc-b987-7e301bf5b86a/billing_emails" \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request_body"
Request body example:
{
"billingEmails": {
"example@email.com": "John",
"billing@company.com": "Billing team"
}
}
| Required | |
|---|---|
billingEmailsmap |
A map of billing emails and names associated with them. There is a maximum of three emails that can be configured. Each entry must have a valid email specified along with a name. |
Get a billing cycle for an org
GET /organizations/:organization_id/billing_cycles/:billing_cycle_id
Retrieves a billing cycle for the organization.
# Retrieve billing cycle
curl "https://cloudmc_endpoint/api/v2/organizations/c01e2bd4-50c4-4ef4-b756-f728823309a4/billing_cycles/8259182d-5234-4a78-adf6-7edc11db2e3b" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": {
"pricingPackages": [
{
"endDate": "2021-12-01",
"packageId": "508a1f5f-2504-41ac-b48f-b87e757840a4",
"name": {
"en": "Cox Pricing Package"
},
"startDate": "2021-11-01"
}
],
"deferred": false,
"invoices": [],
"discounts": [
{
"endDate": "2021-11-11",
"name": {
"en": "Credit 01"
},
"discountId": "e6ada5f6-9806-466c-8522-314da152a8e7",
"type": "CREDIT",
"startDate": "2021-11-01",
"remaining": {
"discountedProducts": {},
"discountedCategories": {},
"packageDiscount": 10.0,
"labels": {}
}
},
],
"endDate": "2021-12-01",
"currency": "USD",
"id": "8259182d-5234-4a78-adf6-7edc11db2e3b",
"state": "IN_PROGRESS",
"startDate": "2021-11-01"
}
}
| Attributes | |
|---|---|
idUUID |
The id of the billing cycle. |
startDatestring |
The start date in ISO 8601 of the billing cyle. |
endDatestring |
The end date in ISO 8601 of the billing cyle. |
currencystring |
The currency associated to the organization. |
deferredboolean |
Indicates whether the billing cycle is deferred or not. |
invoicesArray[UUID] |
Array of UUIDs of the invoices associated with the billing cycle. |
pricingPackagesArray[Object] |
List of pricing packages associated with the billing cycle. |
pricingPackages.endDatestring |
The end date in ISO 8601 of when the pricing package was applied to the billing cycle. |
pricingPackages.startDatestring |
The start date in ISO 8601 of the pricing package associated with the billing cycle. |
pricingPackages.nameMap[String, String] |
The name translations of the pricing package. |
discountsArray[Object] |
List of discounts applied during the billing cycle. |
discounts.endDatedate |
The end date of the discount. |
discounts.startDatedate |
The start date of the discount. |
discounts.nameMap[String, String] |
The name translations of the discount. |
discounts.typeenum |
The type of the discount. It could be either "PERCENTAGE" or "CREDIT". |
discounts.remainingObject |
Tracking of the credits remaining and used for the billing cycle. |
discounts.discountIdUUID |
The UUID of the discount. |
stateenum |
The state of the billing cycle. It could be "NONE", "WAITING_INVOICE", "WAITING_PAYMENT", "PAID", "IN_PROGRESS", or "FUTURE". |
Update the pricing package and discounts starting at a billing cycle
PUT /organizations/:organization_id/billable_info
Updates the organization's billable information with the new pricing package and discounts starting at the specified billing cycle
# Update billable information
curl "https://cloudmc_endpoint/api/v2/organizations/c01e2bd4-50c4-4ef4-b756-f728823309a4/billable_info" \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request_body"
Request body example:
{
"billableOrgInfoId": "1529945f-2254-4242-8633-a49ac237919b",
"billingCycleId": "8f651e10-f8c7-4f26-8ab5-75f2e5bc4f79",
"pricingPackageId": "87cf333a-fb01-4114-971f-da5c972bfece",
"discountIds": [
"033f37c5-9ea4-4caa-9008-5db9118b3d30",
"9254ca94-b12b-4cf4-92c3-d51cef33a229"
]
}
| Attributes | |
|---|---|
billableOrgInfoIdUUID |
The id of the billable organization information. |
billingCycleIdUUID |
The id of the starting billing cycle. |
pricingPackageIdUUID |
The id of pricing package to apply. |
discountIdsArray[UUID] |
The list of discount Ids to apply at the start of the billing cycle. An empty list results in no discounts to apply |
The above command returns a JSON structured like this:
{
"data": {
"organization": {
"id": "0594913c-b909-43dd-9467-79a09219f760"
},
"applicableDiscounts": [],
"currency": "USD",
"id": "a37218aa-3515-49c2-8600-e1a856bebc9b",
"pricingPackage": {
"id": "1529945f-2254-4242-8633-a49ac237919b"
},
"billableStart": "2021-11-22"
}
}
| Response | |
data
Organization | The information about the updated organization
|-------------------------------------|---------------------------------------------------------------------------------------|
|organization
Organization | The organization to which belongs the billing information.|
| currency
String | The currency used by the organization for billing, payments and invoices. |
| id
UUID | The id of billing information. |
| pricingPackage
Object | The pricing package currently applied to the organization. |
| billableStart
String | The the start date when the application start generating billing cycles and invoices. |
| applicableDiscounts
Array[Object] | The discounts applicable to the billable org . |
Users
A user account allows users to authenticate to an organization and to have access to the resources in it. You can restrict user access to the system and environments by assigning them specific roles. Additionally, every user is given an API key which is needed to use our APIs. All operations done by users are persisted and can be accessed through the activity log.
List users
GET /users
# Retrieve visible users
curl "https://cloudmc_endpoint/api/v2/users" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data":[{
"id": "e83540c7-75a0-4715-96dc-c10a364e0390",
"userName": "habsgoalie123",
"firstName": "Carey",
"lastName": "Price",
"email": "gohabsgo@cloud.mc",
"creationDate": "2017-08-15T12:00:00.000Z",
"status": "ACTIVE",
"locale": "en",
"organization": {
"id": "8e3393ce-ee63-4f32-9e0f-7b0200fa655a",
"name": "Canadiens"
},
"serviceConnections": [
{
"id": "5d841eb6-5913-4244-b001-917228e7aa64",
"name": "Microsoft Azure"
},
{
"id": "61e5dc38-441b-4c7d-8ac4-087ebaab23da",
"name": "swifttest"
}
],
"lastLogin": "2022-05-20T15:56:27.000Z",
"lastFailedLogin": "2022-04-16T18:50:21.000Z",
"loginCount": 76,
"failedLoginCount": 10,
"isBusinessContact": false,
"isTechnicalContact": false,
"tfaEnabled": false,
"deleted": false,
"receivesEmailNotifications": false,
"canResendUserCreationEmail": true,
"backupCodesRemaining": 0,
"primaryRoleBinding": {
"id": "013b40ca-9837-4233-b28e-09f5828958e5",
"role": {
"isSystem": true,
"name": "guest",
"id": "ad6b03cc-b9f3-48ae-9406-2ad168afbe01",
"isFixed": true
}
}
}]
}
Retrieve information about users you have access to. If you want access to other users in your organization or sub-organizations, you will need to be assigned the Users read permission. Without this permission, you will only see your own user in the list.
| Attributes | |
|---|---|
idUUID |
The id of the user. |
creationDatestring |
The date in ISO 8601 that the user was created. |
emailstring |
The email of the user. |
firstNamestring |
The first name of the user. |
lastNamestring |
The last name of the user. |
organizationOrganization |
The organization to which the user belongs. |
primaryRoleBindingRoleBinding |
The primary role assigned to this user. This role will always be a fixed role. |
serviceConnectionsArray[ServiceConnection] |
The service connection of the user includes: id, name, serviceCode, type, and state |
statusstring |
The current status of the user. |
userNamestring |
The username of the user |
timezonestring |
The timezone of the user. |
localestring |
The language set for the user. |
lastLoginstring |
The date in ISO 8601 of the last login by the user. |
lastFailedLoginstring |
The date in ISO 8601 of the last failed login by the user. |
loginCountinteger |
The count of successful logins for that user. |
failedLoginCountinteger |
The count of failed logins attempted by the user. |
isBusinessContactboolean |
Indicates whether the user is a business contact. |
isTechnicalContactboolean |
Indicates whether the user is a technical contact. |
receivesEmailNotificationsboolean |
Indicates whether the user email notifications. |
canResendUserCreationEmailboolean |
Indicates whether the user creation email can be sent to the user. |
backupCodesRemaininginteger |
The number of backup codes remaining for the user. |
Retrieve a user
GET /users/:id
# Retrieve visible user
curl "https://cloudmc_endpoint/api/v2/users/fdf60a19-980d-4380-acab-914485111305" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data":{
"id": "fdf60a19-980d-4380-acab-914485111305",
"userName": "frodo",
"firstName": "Frodo",
"lastName": "Baggins",
"email": "frodo@cloud.mc",
"creationDate": "2017-08-15T12:00:00.000Z",
"status": "ACTIVE",
"locale": "en",
"organization": {
"id": "c64dcd1d-9123-45e5-ad00-5d635c49176b",
"name": "The Shire"
},
"serviceConnections": [
{
"serviceCode": "cs-acs-dev2",
"name": "cs-acs-dev2",
"id": "7430e95f-6029-444f-9677-9d2d54007138",
"state": "PROVISIONED",
"type": "cloudstack"
},
{
"serviceCode": "cs-acs-dev1",
"name": "cs-acs-dev1",
"id": "9000c02b-cb33-4e4e-8d7b-f834f48e8fb9",
"state": "ERROR_PROVISIONING",
"type": "cloudstack"
}
],
"lastLogin": "2022-05-20T15:56:27.000Z",
"lastFailedLogin": "2022-04-16T18:50:21.000Z",
"loginCount": 76,
"failedLoginCount": 10,
"isBusinessContact": false,
"isTechnicalContact": false,
"tfaEnabled": false,
"deleted": false,
"receivesEmailNotifications": false,
"canResendUserCreationEmail": true,
"backupCodesRemaining": 0,
"primaryRoleBinding": {
"id": "013b40ca-9837-4233-b28e-09f5828958e5",
"role": {
"isSystem": true,
"name": "guest",
"id": "ad6b03cc-b9f3-48ae-9406-2ad168afbe01",
"isFixed": true
}
}
}
}
Retrieve information about a specific user. If you want access to other users in your organization or sub-organizations, you will need to be assigned the Users Read permission.
| Attributes | |
|---|---|
idUUID |
The id of the user. |
creationDatestring |
The date in ISO 8601 that the user was created. |
emailstring |
The email of the user. |
firstNamestring |
The first name of the user. |
lastNamestring |
The last name of the user. |
organizationOrganization |
The organization to which the user belongs. |
primaryRoleBindingRoleBinding |
The primary role assigned to this user. This role will always be a fixed role. |
serviceConnectionsArray[ServiceConnection] |
The service connection of the user includes: id, name, serviceCode, type, and state |
statusstring |
The current status of the user. |
userNamestring |
The username of the user |
timezonestring |
The timezone of the user. |
localestring |
The language set for the user. |
lastLoginstring |
The date in ISO 8601 of the last login by the user. |
lastFailedLoginstring |
The date in ISO 8601 of the last failed login by the user. |
loginCountinteger |
The count of successful logins for that user. |
failedLoginCountinteger |
The count of failed logins attempted by the user. |
isBusinessContactboolean |
Indicates whether the user is a business contact. |
isTechnicalContactboolean |
Indicates whether the user is a technical contact. |
receivesEmailNotificationsboolean |
Indicates whether the user email notifications. |
canResendUserCreationEmailboolean |
Indicates whether the user creation email can be sent to the user. |
backupCodesRemaininginteger |
The number of backup codes remaining for the user. |
identityProviderUsersArray |
A list of objects containing the ids of users associated with the identity provider, and their subject ids. |
Create user
POST /users
# Create a user
curl -X POST "https://cloudmc_endpoint/api/v2/users" \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request-body"
Request body example:
{
"userName": "vader42",
"firstName": "Anakin",
"lastName": "Skywalker",
"email": "vader42@cloud.mc",
"primaryRoleBinding": {
"role": {
"id": "4a1a44f3-ea74-4952-b9ef-ff3163c329d9",
},
},
"organization": {
"id": "645cf4ce-3699-40c5-a1a8-0b3e945f49ee"
},
}
Create a user in a specific organization.
Users are created asynchronously on the underlying service(s) and progress is reflected in the state of the user's service connection(s).
You will need the Create a new user permission to execute this operation.
| Required | |
|---|---|
userNamestring |
Username of the new user. Should be unique across the organization. |
firstNamestring |
First name of the user. |
lastNamestring |
Last name of the user. |
emailstring |
Email of the user. Should be unique across the organization. |
primaryRoleBinding.role.idUUID |
The id of the primary role to assign to this user |
| Optional | |
|---|---|
organizationOrganization |
Organization in which the user will be created. Defaults to your organization. required: id |
| Response | |
|---|---|
taskIdUUID |
The id of the task |
taskStatusstring |
The status of the task |
datauser |
The information about the created user |
# Response body example
The responses' data field contains the created user with its id.
{
"taskId": "633a85e5-447b-41db-a9a2-da986325955c",
"taskStatus": "PENDING",
"data": {
"id": "c1ad55a9-0301-4925-bedc-106d31a73047",
"userName": "bkenobi",
"email": "bkenobi@gmail.com",
"firstName": "Ben",
"lastName": "Kenobi",
"canResendUserCreationEmail": true,
"deleted": false,
"failedLoginCount": 0,
"isBusinessContact": false,
"isTechnicalContact": false,
"locale": "en",
"loginCount": 0,
"receivesEmailNotifications": false,
"serviceConnections": [],
"status": "ACTIVE",
"tfaEnabled": false,
"organization": {
"id": "bdb2d571-2878-462c-8162-9a034d5ab602",
"name": "System"
},
"primaryRoleBinding": {
"id": "013b40ca-9837-4233-b28e-09f5828958e5",
"role": {
"isSystem": true,
"name": "guest",
"id": "ad6b03cc-b9f3-48ae-9406-2ad168afbe01",
"isFixed": true
}
}
}
}
Update user
PUT /users/:id
# Update a user
curl -X PUT "https://cloudmc_endpoint/api/v2/users/fdf60a19-980d-4380-acab-914485111305" \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request-body"
Request body example:
{
"userName": "spidey1",
"firstName": "Peter",
"lastName": "Parker",
"email": "spidey1@cloud.mc",
"primaryRoleBinding": {
"role": {
"id": "4a1a44f3-ea74-4952-b9ef-ff3163c329d9",
},
},
}
Update a specific user. You will need the Users update permission to execute this operation.
| Optional | |
|---|---|
userNamestring |
The new username of the user. Should be unique across the organization. |
firstNamestring |
The new first name of the user |
lastNamestring |
The new last name of the user |
primaryRoleBinding.role.idUUID |
The id of the primary role to assign to this user |
emailstring |
The new email of the user. Should be unique across the organization. |
Returns
The responses' data field contains the updated user.
Delete user
DELETE /users/:id
Users are deleted asynchronously on the underlying services.
The user model's status will be set to DISABLED prior to attempting the delete operation. This will prevent the user from login in or making API calls.
The user model will be deleted only when the user is removed from all environments AND from all underlying services.
If removing a user from an environment fails, no attempt will be made to delete the user model. This does not affect other attempts at removing the user from a different environment or deleting the user from a different service.
If deleting a user fails, subsequent delete attempts will be considered as a "force delete". A force delete entails reattempting to delete the user as explained above and then deleting the user model regardless of the response from the underlying services.
Delete a specific user. You will need the Delete an existing user permission to execute this operation.
# Delete a user
curl "https://cloudmc_endpoint/api/v2/users/dd01c908-371c-4ec5-9fd7-80b1bfac8975" \
-X DELETE -H "MC-Api-Key: your_api_key"
| Response | |
|---|---|
taskIdUUID |
The id of the task |
taskStatusstring |
The status of the task |
# Response body example
{
"taskId": "cd921b44-ca9f-4f6b-b184-f952e5ab010a",
"taskStatus": "PENDING"
}
Unlock user
POST /users/:id/unlock
# Unlock a user that was locked from the system
curl "https://cloudmc_endpoint/api/v2/users/dd01c908-371c-4ec5-9fd7-80b1bfac8975/unlock" \
-X POST -H "MC-Api-Key: your_api_key"
A user with 10 consecutive unsuccessful logins will be automatically locked by our system. This API can be used to unlock a user in this situation. You will need the Unlock user permission to execute this operation.
Roles
Roles have a number of permissions associated with them and are bound to users with a given scope. They are associated to users through role bindings.
List Roles
GET /roles
Retrieves a list of roles visible to the caller. The user does not have to have explicit access to that role for it to be returned. If a user's permissions on a given context context include all cumulative permissions for all roles a user is bound to that role will be returned in the roles api call.
Example: If a user has a role with env:<entity>:read and env:<entity>:create and another role exists with just env:<entity>:read it will be returned in the API call.
# Retrieve all env-scoped roles applicable to this environment
curl "https://cloudmc_endpoint/api/v2/roles?environment_id=4865a023-1dd5-45a3-a23d-e952ceb7a44a&filter_scope=ENV" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data":[
{
"creationDate":"2019-03-11T22:16:15.000Z",
"version":1,
"isSystem":false,
"isDefault":true,
"deleted":false,
"permissions":[
{
"name":"env:*:*",
"id":"98047553-7a00-450d-afd0-d49eee436603"
}
],
"name":"editor",
"id":"b230cc47-3fad-4759-8ad2-de80bc6ac7e8",
"isFixed":true,
"defaultScope":"ENV",
"pluginName": "cloudstack"
},
{
"creationDate":"2019-03-11T22:16:12.000Z",
"version":1,
"isSystem":false,
"isDefault":false,
"deleted":false,
"permissions":[
{
"name":"env:*:read"
}
],
"name":"viewer",
"id":"f405a594-56c7-43d4-b790-ab8c616253fc",
"isFixed":true,
"defaultScope":"ENV",
"pluginName": "cloudstack"
}
]
}
| Query Params | |
|---|---|
filter_scopeScopeQualifier |
Return only roles with this as the default scope. |
system_onlyboolean |
Return only system roles. |
organization_idUUID |
Return only roles requesting user can assign on this organization. |
environment_idUUID |
Filters out env-scoped roles applicated to this environment. If an environment is of a plugin type that has custom plugin roles it only returns the plugin's roles, if the environment has no plugin defined roles it returns only the default environment-scoped roles. |
ScopeQualifier
ENVORG_BASEORG_TREEORG_SUBORG_TOPLEVELTAG_ANYMATCHGLOBAL
Additional roles
With additional roles, you can allow users access to other organizations. You can specify a scope which targets one or many organizations with a specific role. See roles for more information on roles.
Scoping
There are different types of scope that you can use depending on your use case. This scope must be provided when assigning an additional role to a user. You can only give a scope/role combination to another user if you have a higher or equivalent additional role.
| Scope | Description | Required fields |
|---|---|---|
| ORG_BASE | Applies the role on a specific organization | organization.id |
| ORG_TREE | Applies the role on a specific organization and its sub-organzations | organization.id |
| ORG_SUBS | Applies the role the sub-organzations of a specific organization | organization.id |
| ORG_TOPLEVEL | Applies the role on all top-level organizations | |
| TAGS_ANYMATCH | Applies the role on all organizations that are tagged with at least one the specified tags | tags |
Get additional roles of user
GET /users/:id/additional_roles
# Get additional role of user
curl -X GET "https://cloudmc_endpoint/api/v2/users/:id/additional_roles" \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json"
# Response body example
{
"data": [
{
"id": "ed18cdd0-0fa0-464d-a993-e689d39dfe2e",
"creationDate": "2019-06-06T15:01:22.000Z",
"scopeQualifier": "ORG_BASE",
"primary": false,
"role": {
"id": "cc71a40b-d90b-40db-b724-08d71f5179b5",
"name": "user",
"isSystem": true,
"isFixed": true
},
"organization": {
"name": "Test",
"id": "6861c664-0a83-4e91-bd8c-3a6083e81a13",
"entryPoint": "test"
},
"user": {
"id": "6ebc54bb-c3fe-4434-b412-09ac4f798680",
"firstName": "franz",
"lastName": "franz",
"userName": "franz",
"email": "fgarcia@cloudops.com"
}
}]
}
| Attributes | |
|---|---|
idUUID |
The id of the additional role |
creationDatestring |
The date the additional role was added/updated on the user |
scopeQualifierstring |
The scope of this additional role (ORG_BASE, TAGS_ANYMATCH, GLOBAL, etc..). Please refer to the table above. |
tags[string] |
Organization tags to match for TAGS_ANYMATCH scoping |
roleRole |
The role to apply on the target scope |
organizationOrganization |
The organization of the additional role. Only present on scopes that target a specific organization. includes: id, name, entryPoint |
userUser |
The user that the additional role is applied on includes: id, username, firstName, lastName, email |
primaryboolean |
Indicates whether the role is primary. |
Assign additional role to user
POST /users/:id/additional_roles
# Assign an additional role to user
curl -X POST "https://cloudmc_endpoint/api/v2/users/:id/additional_roles" \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json"
-d "[request_body]"
# Request body example
{
"scopeQualifier": "ORG_BASE",
"role": {
"id": "cc71a40b-d90b-40db-b724-08d71f5179b5",
},
"organization": {
"id": "6861c664-0a83-4e91-bd8c-3a6083e81a13",
},
}
| Required | |
|---|---|
scopeQualifierstring |
The scope of this additional role (ORG_BASE, TAGS_ANYMATCH, GLOBAL, etc..) |
role.idUUID |
The id of the role to apply on the target scope. Operator cannot be used as additional role. |
organization.idUUID |
The id of the target organization of the scope. Only required when using a scope qualifier that targets an organization. |
tagsUUID |
The organization tags of the scope. Only required when using the TAGS_ANYMATCH scope. |
You will need to have Users: Manage permission to execute this operation.
Remove additional role from user
DELETE /users/:user_id/additional_roles/:id
# Remove an additional role from user
curl -X DELETE "https://cloudmc_endpoint/api/v2/users/:user_id/additional_roles/:id" \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json"
You will need to have Users: Manage permission to execute this operation.
Environments
Environments allow you to manage resources of a specific service and to manage your users' access to them. With environment roles, you have tight control of what a user is allowed to do in your environment. A general use case of environments is to split your resources into different deployment environments (e.g. dev, staging and production). The advantage is that resources of different deployments are isolated from each other and you can restrict user access to your most critical resources.
List environments
GET /environments
# Retrieve visible environments
curl "https://cloudmc_endpoint/api/v2/environments" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": [{
"id": "1ee5cd43-8395-4cd5-a20f-0f1e83b7f8bd",
"name": "cheyenne_mountain",
"description": "Environment for base at Cheyenne Mountain",
"metadata": {
"mode": "project"
},
"defaultRole": {
"id": "b7c48102-350e-40b9-9a3e-b7a0b3cfa535",
"name": "Owner",
"isSystem": false,
"isDefault": false,
"deleted": false,
"isFixed": true,
"defaultScope": "ENV",
"creationDate": "2020-01-02T16:04:27.000Z"
},
"membership": "MANY_USERS",
"creationDate": "2017-08-15T12:00:00.000Z",
"organization": {
"id": "a9f93785-0545-4876-8241-3b19b9a86721",
"name": "Acme",
"entryPoint": "acme"
},
"allowExternalMembers": false,
"state": "PROVISIONED",
"serviceConnection": {
"id": "adfbdb51-493b-45b1-8802-3f6327afb9e6",
"name": "Compute - Québec"
},
}]
}
List environments that you have access to. It will only return environments that you're member of if you're not assigned the Environments read permission.
| Attributes | |
|---|---|
idUUID |
The id of the environment |
namestring |
The name of the environment |
descriptionstring |
The description of the environment |
metadataobject |
Additional information about the environment |
membershipstring |
Type of membership of the environment. (e.g. ALL_ORG_USERS, MANY_USERS) |
creationDatestring |
The date in ISO 8601 that the environment was created |
organizationOrganization |
The organization of the environment includes: id, name, entryPoint |
allowExternalMembersboolean |
Indicates if the environment supports external members or not |
defaultRoleobject |
The role that will be assigned to new users logging into the organization |
statestring |
Indicates the state of the environment. Possible states are PROVISIONING, PROVISIONED, ERROR_PROVISIONING, PURGED, PURGING, ERROR_PURGING, and PENDING. |
serviceConnectionServiceConnection |
The service connection of the environment includes: id, name, serviceCode, type |
Retrieve an environment
GET /environments/:id
# Retrieve visible environment
curl "https://cloudmc_endpoint/api/v2/environments/487a2745-bb8a-44bc-adb1-e3b048f6def2" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": {
"id": "1ee5cd43-8395-4cd5-a20f-0f1e83b7f8bd",
"name": "cheyenne_mountain",
"description": "Environment for base at Cheyenne Mountain",
"metadata": {
"mode": "project"
},
"defaultRole": {
"id": "b7c48102-350e-40b9-9a3e-b7a0b3cfa535",
"name": "Owner",
"isSystem": false,
"isDefault": false,
"deleted": false,
"isFixed": true,
"defaultScope": "ENV",
"creationDate": "2020-01-02T16:04:27.000Z"
},
"membership": "MANY_USERS",
"creationDate": "2017-08-15T12:00:00.000Z",
"organization": {
"id": "a9f93785-0545-4876-8241-3b19b9a86721",
"name": "Acme",
"entryPoint": "acme"
},
"allowExternalMembers": false,
"state": "PROVISIONING",
"serviceConnection": {
"id": "adfbdb51-493b-45b1-8802-3f6327afb9e6",
"name": "Compute - Québec"
},
}
}
Retrieve an environment you have access to. You can always retrieve environments that you're a member of but to access other environments you will need the Environments read permission.
| Attributes | |
|---|---|
idUUID |
The id of the environment |
namestring |
The name of the environment |
descriptionstring |
The description of the environment |
metadataobject |
Additional information about the environment |
membershipstring |
Type of membership of the environment. (e.g. ALL_ORG_USERS, MANY_USERS) |
creationDatestring |
The date in ISO 8601 that the environment was created |
organizationOrganization |
The organization of the environment includes: id, name, entryPoint |
allowExternalMembersboolean |
Indicates if the environment supports external members or not |
defaultRoleobject |
The role that will be assigned to new users logging into the organization |
statestring |
Indicates the state of the environment. Possible states are PROVISIONING, PROVISIONED, ERROR_PROVISIONING, PURGED, PURGING, ERROR_PURGING, and PENDING. |
serviceConnectionServiceConnection |
The service connection of the environment includes: id, name, serviceCode, type |
Create environment
POST /environments
Environments are created asynchronously on the underlying service. When creating an environment any underlying actions performed by the plugin is done asynchronously to the creation of the model, and its progress is reflected in the state of the environment.
# Create an environment
curl -X POST "https://cloudmc_endpoint/api/v2/environments" \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request_body"
Request body example:
{
"name": "glados",
"description": "Environment property of Aperture Science",
"membership": "MANY_USERS",
"organization": {
"id": "2fd60d6f-1fee-4fe5-8ec6-46d8776acc6f"
},
"serviceConnection": {
"id": "7f0fa906-490a-467b-bc44-e2382d43015e"
}
}
| Required | |
|---|---|
namestring |
The name of the new environment. Should be unique in the environment and only contain lower case characters, numbers, dashes and underscores. |
serviceConnectionServiceConnection |
The service connection that the environment should be created in required: id |
| Optional | |
|---|---|
descriptionstring |
The description of the new environment. |
organizationOrganization |
The organization that the environment should be created in. Defaults to your organization required: id |
membershipstring |
Type of membership of the environment. ALL_ORG_USERS will add every user in the organization to this environment with the default role. MANY_USERS will allow you to choose the users you want in the environment and assigned them specific roles. Defaults to MANY_USERS |
| Response | |
|---|---|
taskIdUUID |
The id of the task |
taskStatusstring |
The status of the task |
dataEnvironment |
The information about the created environment |
# Response body example
{
"taskId": "a82113b9-7f76-4354-ae27-b18b0204d50f",
"status": "PENDING",
"data": {
"id": "a83e131f-4114-432b-a3fb-fd4c58907860",
"name": "environment-name",
"defaultRole": {
"id": "9f4d940d-708d-4784-98bd-926195691e34",
"name": "Owner",
"isSystem": false,
"isDefault": false,
"deleted": false,
"isFixed": true,
"defaultScope": "ENV",
"creationDate": "2019-09-04T19:40:11.000Z"
},
"membership": "MANY_USERS",
"deleted": false,
"organization": {
"id": "52fd201e-aa82-4a27-86b3-ea9650a7fb1e",
"name": "organization-name",
"entryPoint": "system"
},
"allowExternalMembers": false,
"state": "PENDING",
"serviceConnection": {
"id": "95ed7fa3-6f51-405e-b2c3-de43f20de2c3"
}
}
}
Update environment
Environments are updated asynchronously on the underlying service. When updating an environment any underlying actions performed by the plugin is done asynchronously to the update of the model. The state of the environment will remain in the PROVISIONED state. The task returned in the response can be used to track the progress of the asynchronous update.
If the membership mode is changed, users will also be added or removed asynchronously to / from the environment. The progress of the task can be tracked via the task id.
PUT /environments/:id
# Update an environment
curl -X POST "https://cloudmc_endpoint/api/v2/environments/f9dea588-d7ab-4f42-b6e6-4b85f273f3db" \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request_body"
Request body example:
{
"name": "skynet-beta-v2",
"description": "Environment for the Skynet project (updated)",
}
| Optional | |
|---|---|
namestring |
The updated name of the environment. Should be unique in the environment and only contain lower case characters, numbers, dashes and underscores. |
descriptionstring |
The updated description of the environment |
membershipstring |
Type of membership of the environment. ALL_ORG_USERS will add every user in the organization to this environment with the default role. MANY_USERS will allow you to choose the users you want in the environment and assigned them specific roles. Defaults to MANY_USERS |
| Response | |
|---|---|
taskIdUUID |
The id of the task |
taskStatusstring |
The status of the task |
dataEnvironment |
The information about the updated environment |
# Response body example
{
"taskId": "105cddf8-4507-4131-87eb-fe383bbd882b",
"taskStatus": "PENDING",
"data": {
"id": "d77de7ad-274e-4ec9-8776-8d748b0671fd",
"name": "skynet-beta-v2",
"metadata": {
"mode": "project"
},
"defaultRole": {
"id": "b7c48102-350e-40b9-9a3e-b7a0b3cfa535",
"name": "Owner",
"isSystem": false,
"isDefault": false,
"deleted": false,
"isFixed": true,
"defaultScope": "ENV",
"creationDate": "2020-01-02T16:04:27.000Z",
},
"description": "Environment for the Skynet project (updated)",
"membership": "MANY_USERS",
"creationDate": "2020-02-27T16:23:20.000Z",
"deleted": false,
"organization": {
"name": "System",
"id": "f6ece376-de9e-45d5-8719-82a279664ea9",
"entryPoint": "system"
},
"allowExternalMembers": false,
"state": "PROVISIONED",
"serviceConnection": {
"serviceCode": "acs-dev-1",
"name": "acs-dev-1",
"id": "8901494c-01ee-4d6b-bd12-cd5347127039",
"type": "cloudstack"
}
}
}
You will need the Environments update permission to execute this operation.
Delete environment
DELETE /environments/:id
Environments are deleted asynchronously on the underlying service. The environment model will only be deleted if the environment is deleted sucessfully in the underlying service.
If deleting an environment fails in the underlying service, subsequent delete attempts are considered a "force delete". A force delete entails attempting deleting the environment from the underlying service and then deleting the environment model regardless of the response from the underlying service.
# Delete an environment
curl "https://cloudmc_endpoint/api/v2/environments/f9dea588-d7ab-4f42-b6e6-4b85f273f3db" \
-X DELETE -H "MC-Api-Key: your_api_key"
# Response body example
Delete a specific environment. You will need a role with the Delete an existing environment permission to execute this operation.
{
"taskId": "1ac94e11-a8cf-45d9-ba0c-6bd7f797a8a4",
"taskStatus": "PENDING"
}
| Attributes | |
|---|---|
taskIdUUID |
The id of the task |
taskStatusstring |
The status of the task |
List members
GET /environments/:id/members
# Retrieve visible user
curl "https://cloudmc_endpoint/api/v2/environments/[env-id]/members" \
-H "MC-Api-Key: your_api_key"
# Response body example
{
"data": [
{
"id": "00977373-3eae-4d26-84df-68817f97b072",
"creationDate": "2019-05-16T20:39:28.000Z",
"state": "PROVISIONED",
"role": {
"id": "46fb36d8-6888-48ed-ab13-711fd19f0873",
"name": "viewer",
},
"user": {
"id": "ae3f1a72-e2b6-4865-856b-b3cf47ab8eb7",
"firstName": "patatat",
"lastName": "patatat",
"userName": "patatat",
"email": "pdube@cloudops.com"
},
"metadata": {
"membership": "All"
},
"environment": {
"id": "094e1dee-164b-4b32-be29-e6b4e27e7713"
},
"scopeQualifier": "ENV"
},
]
}
List all the users in an environment that you have access to.
| Attributes | |
|---|---|
idUUID |
The id of the binding between the user and the environment |
creationDatestring |
The date the user membership was either created or updated. |
roleRole |
The role of the user in the environment includes: id and name |
userUser |
A member of the environmment includes: id, firstName, lastName, userName and email |
metadata.membershipstring |
"All" if automatically added from the ALL_ORG_USERS membership. "Many" if added manually to the org. |
environment.idUUID |
The id of the environment the user is part of. |
scopeQualifierstring |
The scope qualifier for the user. Possible value: ENV. |
You will need to either be owner on the environment or have the Environments: Own All permission to execute this operation.
Add member
POST /environments/:id/members
# Add an environment member
curl -X POST "https://cloudmc_endpoint/api/v2/environments/[environment-id]/members" \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "[request_body]"
# Request body example
{
"user": {
"id": "e3f01d38-c9e7-4959-9580-a8e84af2add1"
},
"role": {
"id": "9ffd4630-4e2b-4c84-b200-3240d7c26dc6"
}
}
# Response body example
{
"taskId": "a82113b9-7f76-4354-ae27-b18b0204d50f",
"status": "PENDING"
}
Add a user to an environment that you have access to.
| Required | |
|---|---|
user.idUUID |
The user that will be added to the environment. |
role.idUUID |
The role that the user will have in the environment. |
You will need to either be owner on the environment or have the Environments: Own All permission to execute this operation.
Update member
PUT /environments/:env_id/members/:user_id
# Update an environment member
curl -X PUT "https://cloudmc_endpoint/api/v2/environments/[environment-id]/members/[user-id]" \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "[request_body]"
# Request body example
{
"role": {
"id": "9ffd4630-4e2b-4c84-b200-3240d7c26dc6"
}
}
Update a user in an environment that you have access to.
| Required | |
|---|---|
role.idUUID |
The new role that the user will have in the environment. |
You will need to either be owner on the environment or have the Environments: Own All permission to execute this operation.
Remove member
Members of environment are deleted asynchronously on the underlying service. The environment member will only be deleted if the member is deleted sucessfully in the underlying environment service.
If deleting an member fails in the underlying environment service, subsequent delete attempts are considered a "force delete". A force delete entails attempting deleting the member from the underlying environment service and then deleting the member model regardless of the response from the underlying service.
DELETE /environments/:env_id/members/:user_id
# Remove a member from an environment
curl -X DELETE "https://cloudmc_endpoint/api/v2/environments/[environment-id]/members/[user-id]" \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json"
# Response body example
{
"taskId": "a82113b9-7f76-4354-ae27-b18b0204d50f",
"status": "PENDING"
}
| Attributes | |
|---|---|
taskIdUUID |
The id of the task |
taskStatusstring |
The status of the task |
You will need to either be owner on the environment or have the Environments: Own All permission to execute this operation.
Default environment membership
PUT /environments/:id/membership
# Update default environment membership
curl -X PUT "https://cloudmc_endpoint/api/v2/environments/[environment-id]/membership" \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "[request_body]"
# Request body example
{
"membership": "ALL_ORG_USERS",
"defaultRole": {
"id": "f05ff413-0d6d-4054-bbee-a720de5f1a4c"
}
}
Update the default membership of an environment that you own.
The above command returns a JSON structured like this:
{
"data": {
"id": "1ee5cd43-8395-4cd5-a20f-0f1e83b7f8bd",
"name": "cheyenne_mountain",
"description": "Environment for base at Cheyenne Mountain",
"metadata": {
"mode": "project"
},
"defaultRole": {
"id": "b7c48102-350e-40b9-9a3e-b7a0b3cfa535",
"name": "Owner",
"isSystem": false,
"isDefault": false,
"deleted": false,
"isFixed": true,
"defaultScope": "ENV",
"creationDate": "2020-01-02T16:04:27.000Z"
},
"membership": "MANY_USERS",
"creationDate": "2017-08-15T12:00:00.000Z",
"organization": {
"id": "a9f93785-0545-4876-8241-3b19b9a86721",
"name": "Acme",
"entryPoint": "acme"
},
"allowExternalMembers": false,
"state": "PROVISIONING",
"serviceConnection": {
"id": "adfbdb51-493b-45b1-8802-3f6327afb9e6",
"name": "Compute - Québec"
},
}
}
| Optional | |
|---|---|
membershipstring |
ALL_ORG_USERS if you want all users of the organization to be member of the environment. MANY_USERS if you want to manually manage members of the environment. |
defaultRole.idUUID |
The default role to give to a user that was added to the environment. |
You will need to either be owner on the environment or have the Environments: Own All permission to execute this operation.
Commitments
A commitment is a set of resources given to a customer at a certain price. A customer will only pay more than the negotiated price if they go over their committed resource.
List commitments
GET /commitments?:organization_id=:id&from=2022-01-01&to=2023-01-01
Retrieves the list of commitments associated with an organization.
# Retrieve organization commitment list
curl "https://cloudmc_endpoint/api/v2/commitments" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": [
{
"committedProducts": [
{
"createdAt": "2022-06-17T18:48:25Z",
"product": {
"id": "bcd82514-d539-4d66-aaf4-b24a95ebe1cd",
"sku": "CVM-1M02"
},
"committedAmount": 1000.0,
"id": "52a54cde-0e5d-4168-9827-5967ded6095e",
"updatedAt": "2022-06-17T18:48:25Z"
}
],
"endDate": "2023-01-01T00:00:00Z",
"pricingMethod": "FIXED_PRICE",
"type": "RESOURCE",
"fixedPrice": 500.0,
"createdAt": "2022-06-17T18:48:07Z",
"organization": {
"name": "SleepyCo",
"id": "42a54cde-0e5d-4168-9827-5967ded6095e"
},
"reseller": {
"name": "SleepyParentCo",
"id": "55a89cde-0e5d-4168-9827-5967ded6095e"
},
"name": "fixed price commitment",
"id": "52a54cde-0e5d-4168-9827-5967ded6095e",
"terminated": false,
"startDate": "2022-01-01T00:00:00Z",
"updatedAt": "2022-06-17T18:48:07Z",
"status": "IN_PROGRESS"
},
{
"committedProducts": [
{
"createdAt": "2022-06-17T18:49:50Z",
"product": {
"id": "bcd82514-d539-4d66-aaf4-b24a95ebe1cd",
"sku": "CVM-1M02"
},
"fixedRateReferencePrice": 10.0,
"discountAmount": 0.1,
"committedAmount": 1000.0,
"id": "62a54cde-0e5d-4168-9827-5967ded6095e",
"updatedAt": "2022-06-17T18:49:50Z"
}
],
"endDate": "2023-01-01T00:00:00Z",
"pricingMethod": "UTILITY_DISCOUNT",
"rateType": "FIXED_RATE",
"type": "RESOURCE",
"createdAt": "2022-06-17T18:49:38Z",
"organization": {
"name": "SleepyCo",
"id": "42a54cde-0e5d-4168-9827-5967ded6095e"
},
"reseller": {
"name": "SleepyParentCo",
"id": "55a89cde-0e5d-4168-9827-5967ded6095e"
},
"name": "fixed rate commitment",
"id": "62a54cde-0e5d-4168-9827-5967ded6095e",
"terminated": false,
"startDate": "2022-01-01T00:00:00Z",
"updatedAt": "2022-06-17T18:49:38Z",
"status": "IN_PROGRESS"
}
]
}
| Optional Query Parameters | |
|---|---|
organization_idUUID |
The id of the organization that is associated to the commitment. If not provided, will default to the calling user's organization. |
fromstring |
Used as part of a date range query. Denotes the inclusive start date in the format YYYY-MM-DD. Cannot be after to. |
tostring |
Used as part of a date range query. Denotes the exclusive end date in the format YYYY-MM-DD. Cannot be before from. |
The parameters from and to are used to retrieve commitments applicable during a specific date range. They must be used together otherwise the individual parameter is ignored.
| Attributes | |
|---|---|
idstring |
The id of the commitment. |
namestring |
The name of the commitment. |
organizationOrganization |
The organization that is associated to the commitment. |
committedProductsArray[CommittedProduct] |
The list of products, commitment levels and negotiated price associated to the commitment. |
pricingMethodenum |
The pricing method of the commitment. Possible values are: FIXED_PRICE and UTILITY_DISCOUNT. Used to define how the effective price of the commitment is calculated. |
rateTypeenum |
The rate type of the commitment. Applies only to commitments with pricing method UTILITY_DISCOUNT. Possible values are: FIXED_RATE and VARIABLE_RATE. |
statusenum |
The status of the commitment. Possible values are: IN_PROGRESS, UPCOMING, and EXPIRED. |
typeenum |
The type of the commitment. Currently limited to only RESOURCE. |
fixedPricedouble |
The effective price for this commitment. Applies only to commitments with pricing method FIXED_PRICE. |
startDatedate |
The start date of the commitment. |
endDatedate |
The end date of the commitment. |
terminatedBoolean |
A flag denoting whether or not the commitment is terminated. This value is not directly tied to the status. |
createdAtstring |
The date on which the commitment product was created. |
updatedAtstring |
The date on which the commitment product was updated. |
Object: Organization
| Attributes | |
|---|---|
idUUID |
The id of the organization. |
namestring |
The name of the organization. |
Object: CommittedProduct
| Attributes | |
|---|---|
idUUID |
The id of the committed product. |
productProduct |
A product defined in the commitment. |
priceCreatedAtdouble |
The product's price when the commitment was created. |
discountAmountdouble |
The product's discount percentage. |
committedAmountdouble |
The product's committed usage amount. |
createdAtstring |
The date on which the committed product was created. |
updatedAtstring |
The date on which the committed product was updated. |
Object: Product
| Attributes | |
|---|---|
idUUID |
The id of the product. |
skustring |
The sku of the product. |
Get commitment
GET /commitments/:id
Retrieves a commitment's details.
# Retrieves organization's commitment
curl "https://cloudmc_endpoint/api/v2/commitments/52a54cde-0e5d-4168-9827-5967ded6095e" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": {
"committedProducts": [
{
"createdAt": "2022-06-17T18:48:25Z",
"product": {
"id": "bcd82514-d539-4d66-aaf4-b24a95ebe1cd",
"sku": "CVM-1M02"
},
"committedAmount": 1000.0,
"id": "52a54cde-0e5d-4168-9827-5967ded6095e",
"updatedAt": "2022-06-17T18:48:25Z"
}
],
"endDate": "2023-01-01T00:00:00Z",
"pricingMethod": "FIXED_PRICE",
"type": "RESOURCE",
"fixedPrice": 500.0,
"createdAt": "2022-06-17T18:48:07Z",
"organization": {
"name": "SleepyCo",
"id": "42a54cde-0e5d-4168-9827-5967ded6095e"
},
"reseller": {
"name": "SleepyParentCo",
"id": "55a89cde-0e5d-4168-9827-5967ded6095e"
},
"name": "fixed price commitment",
"id": "52a54cde-0e5d-4168-9827-5967ded6095e",
"terminated": false,
"startDate": "2022-01-01T00:00:00Z",
"updatedAt": "2022-06-17T18:48:07Z",
"status": "IN_PROGRESS"
}
}
| Attributes | |
|---|---|
idstring |
The id of the commitment. |
namestring |
The name of the commitment. |
organizationOrganization |
The organization that is associated to the commitment. |
resellerOrganization |
The organization that owns the commitment. |
committedProductsArray[CommittedProduct] |
The list of products, commitment levels and negotiated price associated to the commitment. |
pricingMethodenum |
The pricing method of the commitment. Possible values are: FIXED_PRICE and UTILITY_DISCOUNT. Used to define how the effective price of the commitment is calculated. |
rateTypeenum |
The rate type of the commitment. Applies only to commitments with pricing method UTILITY_DISCOUNT. Possible values are: FIXED_RATE and VARIABLE_RATE. |
statusenum |
The status of the commitment. Possible values are: IN_PROGRESS, UPCOMING, and EXPIRED. |
typeenum |
The type of the commitment. Currently limited to only RESOURCE. |
fixedPricedouble |
The effective price for this commitment. Applies only to commitments with pricing method FIXED_PRICE. |
startDatedate |
The start date of the commitment. |
endDatedate |
The end date of the commitment. |
terminatedBoolean |
A flag denoting whether or not the commitment is terminated. This value is not directly tied to the status. |
createdAtstring |
The date on which the commitment product was created. |
updatedAtstring |
The date on which the commitment product was updated. |
Object: Organization
| Attributes | |
|---|---|
idUUID |
The id of the organization. |
namestring |
The name of the organization. |
Object: CommittedProduct
| Attributes | |
|---|---|
idUUID |
The id of the committed product. |
productProduct |
A product defined in the commitment. |
fixedRateReferencePricedouble |
The product's price when the commitment was created. |
discountAmountdouble |
The product's discount percentage. |
committedAmountdouble |
The product's committed usage amount. |
createdAtstring |
The date on which the committed product was created. |
updatedAtstring |
The date on which the committed product was updated. |
Object: Product
| Attributes | |
|---|---|
idUUID |
The id of the product. |
skustring |
The sku of the product. |
Create commitment
POST /commitments
Creates a commitment to be associated with an organization.
# Create a commitment
curl "https://cloudmc_endpoint/api/v2/commitments" \
-X POST -H "MC-Api-Key: your_api_key"
Request body example for FIXED_PRICE commitments
{
"committedProducts": [
{
"product": {
"id": "73ebf9c8-ecf7-4ee6-b881-150023d5f422"
},
"committedAmount": 1000.0
}
],
"endDate": "2023-01-01T00:00:00Z",
"pricingMethod": "FIXED_PRICE",
"type": "RESOURCE",
"fixedPrice": 500.0,
"organization": {
"id": "e2c00fdb-d493-422c-889f-eb734806b80e"
},
"name": "fixed monthly price commitment",
"startDate": "2022-06-01T00:00:00Z"
}
The above command returns a JSON structured like this:
{
"data": {
"committedProducts": [{
"createdAt": "2022-06-29T21:03:36.731Z",
"product": {
"id": "73ebf9c8-ecf7-4ee6-b881-150023d5f442",
"sku": "f"
},
"committedAmount": 1000.0,
"id": "6dc908c1-3e52-4dc1-b12d-b9de518aae7a",
"updatedAt": "2022-06-29T21:03:36.731Z"
}],
"endDate": "2023-01-01T00:00:00Z",
"pricingMethod": "FIXED_PRICE",
"type": "RESOURCE",
"fixedPrice": 500.0,
"createdAt": "2022-06-29T21:03:36.708Z",
"organization": {
"name": "subOrg",
"id": "e2c00fdb-d493-422c-889f-eb734806b80e"
},
"name": "fixed monthly price commitment",
"id": "aa7c81ab-478a-496b-a0ae-8f30459b0fa5",
"terminated": false,
"startDate": "2022-06-01T00:00:00Z",
"updatedAt": "2022-06-29T21:03:36.708Z"
}
}
Request body example for UTILITY_DISCOUNT commitments
{
"committedProducts": [{
"product": {
"id": "73ebf9c8-ecf7-4ee6-b881-150023d5f442"
},
"committedAmount": 1000.0,
"discountAmount": 10
}],
"endDate": "2023-01-01T00:00:00Z",
"pricingMethod": "UTILITY_DISCOUNT",
"rateType": "FIXED_RATE",
"type": "RESOURCE",
"organization": {
"id": "e2c00fdb-d493-422c-889f-eb734806b80e"
},
"name": "fixed price commitment",
"startDate": "2022-06-01T00:00:00Z"
}
The above command returns a JSON structured like this:
{
"data": {
"committedProducts": [{
"createdAt": "2022-06-29T21:06:55.163Z",
"product": {
"id": "73ebf9c8-ecf7-4ee6-b881-150023d5f442",
"sku": "f"
},
"discountAmount": 10,
"committedAmount": 1000.0,
"fixedRateReferencePrice": 10,
"id": "4a7be20e-23f2-4e83-883e-8e5c56e7552a",
"updatedAt": "2022-06-29T21:06:55.163Z"
}],
"endDate": "2023-01-01T00:00:00Z",
"pricingMethod": "UTILITY_DISCOUNT",
"type": "RESOURCE",
"rateType": "FIXED_RATE",
"createdAt": "2022-06-29T21:06:55.153Z",
"organization": {
"name": "subOrg",
"id": "e2c00fdb-d493-422c-889f-eb734806b80e"
},
"name": "fixed rate commitment",
"id": "7e2c15ae-c43b-44e9-9bbb-8e8821740f53",
"terminated": false,
"startDate": "2022-06-01T00:00:00Z",
"updatedAt": "2022-06-29T21:06:55.153Z"
}
}
| Attributes | |
|---|---|
namestring |
The name of the commitment. |
organizationOrganization |
The organization that is associated to the commitment. |
committedProductsArray[CommittedProduct] |
The list of products, commitment levels and negotiated price associated to the commitment. |
pricingMethodenum |
The pricing method of the commitment. Possible values are: FIXED_PRICE and UTILITY_DISCOUNT. Used to define how the effective price of the commitment is calculated. |
rateTypeenum |
The rate type of the commitment. Applies only to commitments with pricing method UTILITY_DISCOUNT. Possible values are: FIXED_RATE and VARIABLE_RATE. |
typeenum |
The type of the commitment. Currently limited to only RESOURCE. |
fixedPricedouble |
The effective price for this commitment. Applies only to commitments with pricing method FIXED_PRICE. |
startDatedate |
The start date of the commitment. The start date must be specified. A commitment's date range cannot span a billing cycle with an issued invoice. |
endDatedate |
The end date of the commitment. An indefinite end date can be set by omitting the endDate field from the request body. |
Object: Organization
| Attributes | |
|---|---|
idUUID |
The id of the organization. |
Object: CommittedProduct
| Attributes | |
|---|---|
productProduct |
A product defined in the commitment. |
discountAmountdouble |
The product's discount percentage. Applies only to commitments with pricing method UTILITY_DISCOUNT. |
committedAmountdouble |
The product's committed usage amount. |
Object: Product
| Attributes | |
|---|---|
idUUID |
The id of the product. |
Delete commitment
DELETE /commitments/:id
Deletes a commitment that has already been created for an organization.
A commitment can only be deleted if it has no closed billing cycles associated to it. This means that a commitment will likely only be able to be deleted within a month of creation at most.
# delete commitment
curl "https://cloudmc_endpoint/api/v2/commitments/:id" \
-X DELETE -H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"taskId": "taskId...",
"taskStatus": "SUCCESS"
}
Terminate commitment
POST /commitments/:id/terminate
Terminates a commitment that spans a closed billing cycle.
A commitment cannot be deleted if it has a closed billing cycle associated to it. Therefore, it has to be terminated.
A reprocess of the usage may be necessary if the termination date of the commitment is before the current date.
# terminate commitment
curl "https://cloudmc_endpoint/api/v2/commitments/:id/terminate" \
-X POST -H "MC-Api-Key: your_api_key" -d '{"endDate": "YYYY-MM-DD"}'
| Attributes | |
|---|---|
endDatestring |
The termination date of the commitment. The termination date has to correspond to the end date of the current billing cycle or the next billing cycle. |
Request body example for a terminated commitments
{
"endDate": "2022-09-01"
}
The above command returns a JSON structured like this:
{
"taskId": "75a68ec2-d63e-4bc9-b485-8d5a3cc33d4f",
"taskStatus": "SUCCESS"
}
Update commitment
PUT /commitments/:id
Update the attributes of a commitment for an organization
If an invoice hasn't been issued to the customer, all of the attributes of the commitment can be updated.
A commitment that is pre-paid can be updated, but it will be terminated and a new commitment will be created with the updated attributes and will be effective at the start at the end of the current billing cycle.
# update commitment
curl "https://cloudmc_endpoint/api/v2/commitments/:id" \
-X PUT -H "MC-Api-Key: your_api_key" -d '{ ... }'
Request body example
{
"id": "60d16762-bec2-4d5a-916d-15c81b6c2d98"
"name": "updated fixed monthly price commitment",
"committedProducts": [
{
"product": {
"id": "73ebf9c8-ecf7-4ee6-b881-150023d5f422"
},
"committedAmount": 1234.0
}
],
"pricingMethod": "FIXED_PRICE",
"type": "RESOURCE",
"fixedPrice": 550.0,
"fixedPriceTaxCode": {
"code": "SI086690",
"description": "IT Services"
},
"startDate": "2022-06-01T00:00:00Z",
"endDate": "2023-01-01T00:00:00Z"
}
The above command returns a JSON structured like this:
{
"taskId": "75a68ec2-d63e-4bc9-b485-8d5a3cc33d4f",
"taskStatus": "SUCCESS"
}
| Attributes | |
|---|---|
idstring |
The identifier of the commitment. |
namestring |
The name of the commitment. |
organizationOrganization |
The organization that is associated to the commitment. |
resellerOrganization |
The organization that owns the commitment. |
committedProductsArray[CommittedProduct] |
The list of products, commitment levels and negotiated price associated to the commitment. |
pricingMethodenum |
The pricing method of the commitment. Possible values are: FIXED_PRICE and UTILITY_DISCOUNT. Used to define how the effective price of the commitment is calculated. |
rateTypeenum |
The rate type of the commitment. Applies only to commitments with pricing method UTILITY_DISCOUNT. Possible values are: FIXED_RATE and VARIABLE_RATE. |
typeenum |
The type of the commitment. Currently limited to only RESOURCE. |
fixedPricedouble |
The effective price for this commitment. Applies only to commitments with pricing method FIXED_PRICE. |
fixedPriceTaxCodeTaxCode |
The chosen tax code for this commitment. Applies only to commitments with pricing method FIXED_PRICE. |
startDatedate |
The start date of the commitment. The start date must be specified. A commitment's date range cannot span a billing cycle with an issued invoice. |
endDatedate |
The end date of the commitment. An indefinite end date can be set by omitting the endDate field from the request body. |
NOTE: The organization and the reseller attribute cannot be updated
Object: TaxCode
| Attributes | |
|---|---|
codeUUID |
The tax code. |
descriptionProduct |
Optional description or category for given tax code. |
Usage
List organization usage summary
GET /usage_summary/organizations/:id
# Retrieve usage summary in JSON
curl "https://cloudmc_endpoint/api/v2/usage_summary/organizations/03bc22bd-adc4-46b8-988d-afddc24c0cb5?start_date=2017-05-01&end_date=2017-05-15&format=json" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": [{
"organizationId": "52fd201e-aa82-4a27-86b3-ea9650a7fb1e",
"serviceConnectionId": "beeba736-0451-49b0-8020-8b93ed5abb35",
"serviceConnectionPricingId": "e37cc44a-47b6-4a26-81f5-1dbf85433e36",
"utilityCost": 0.66,
"utilityUsage": 5.49999878,
"startDate": "2017-05-01T00:00:00.000Z",
"endDate": "2017-05-01T01:00:00.000Z",
"usageType": "1",
"secondaryType": "RAM"
}]
}
# Retrieve usage summary in CSV
curl "https://cloudmc_endpoint/api/v2/usage_summary/organizations/03bc22bd-adc4-46b8-988d-afddc24c0cb5?start_date=2017-05-01&end_date=2017-05-15&format=csv" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
organizationId,serviceConnectionId,startDate,endDate,usageType,secondaryType,serviceConnectionPricingId,utilityCost,utilityUsage
52fd201e-aa82-4a27-86b3-ea9650a7fb1e,beeba736-0451-49b0-8020-8b93ed5abb35,2017-05-01T00:00:00.000Z,2017-05-01T01:00:00.000Z,1,RAM,e37cc44a-47b6-4a26-81f5-1dbf85433e36,0.660000,5.49999878
Retrieve the usage summary records for an organization and all of its sub-organizations for a specific period. The response can be in JSON (default) or CSV format. Additionally, you can aggregate these records using the different query parameters available.
Note: Old records are aggregated by day instead of hour. If you try to query those records per hour, then you will receive an empty list.
| Attributes | |
|---|---|
organizationIdUUID |
Id of the organization. |
serviceConnectionIdUUID |
Id of the service connection. |
serviceConnectionPricingIdUUID |
Id of the service connection pricing. |
utilityCoststring |
Utility cost of the record (aggregated per the period). |
utilityUsagestring |
Utility usage of the record. |
startDatestring |
Start date of the record in ISO 8601. |
endDatestring |
End date of the record in ISO 8601. |
usageTypestring |
Usage type of the record. |
secondaryTypestring |
Secondary type of the record. |
Note: The utilityUsage reported by this API is the total usage recorded for the specified period. The resource commitment is not taken into account for this endpoint but is outlined in the endpoint /top_level/organizations/{org_id} below.
| Query Parameters (required) | |
|---|---|
start_dateString |
Start date (inclusive). Should have the following format YYYY-MM-DD. |
end_dateString |
End date (exclusive). Should have the following format YYYY-MM-DD. |
| Query Parameters | |
|---|---|
service_connection_idUUID |
Show usage summary for this service connection. |
include_sub_orgsboolean |
Include usage summary of all its sub-organizations. Defaults to false. |
include_costboolean |
Include the utility cost and service connection pricing id fields. Defaults to true. |
include_free_usageboolean |
Include all summary records that has no cost associated to it (i.e. utilityCost == 0). Defaults to true. |
combine_usage_typesboolean |
Sums up the utility cost per organization and service connection. The following fields are removed from the output: serviceConnectionPricingId, usageType, secondaryType, utilityUsage. |
periodString |
The period on which the aggregation is made. HOUR, DAY or PERIOD. The default is HOUR. |
formatString |
JSON or CSV. Defaults to JSON. |
include_deletedboolean |
Will find usage of an organization that may have been deleted. |
List top level organization usage summary
GET /usage_summary/top_level/organizations/:id
# Retrieve usage summary in JSON
curl -X GET \
'https://cloudmc_endpoint/api/v2/usage_summary/top_level/organizations/52fd201e-aa82-4a27-86b3-ea9650a7fb1e?start_date=2019-03-12&end_date=2019-03-13' \
-H 'content-type: application/json' \
-H 'mc-api-key: your_api_key' \
The above command returns a JSON structured like this:
{
"data": [
{
"organizationId": "52fd201e-aa82-4a27-86b3-ea9650a7fb1e",
"serviceConnectionId": "818fa22d-1621-4cf3-87c3-4c10b146524c",
"serviceConnectionPricingId": "c2e38b0d-9b6e-4e79-959f-731cf3d00b1a",
"usageType": "1",
"secondaryType": "RAM",
"utilityCost": 0.480000,
"utilityUsage": 3.99999910,
"resourceCommitmentUsage": 1.0000000,
"startDate": "2019-03-12T00:00:00Z",
"endDate": "2019-03-12T01:00:00Z"
}]
}
Retrieves the usage summary records for top level organization and its sub-organizations for a specific period ensuring that usage is split between two buckets, resource commitment usage and utility usage. The response format will be in the JSON format.
Resource Commitment Usage:
The usage that is counted toward a pre assigned pool of resources defined by the Resource Commitment of the organization on a specified service connection. The resource commitment usage is capped by the resource commitment capacity which is the total amount of resource allocated to the organization.
Utility Usage:
Usage that bursts outside of the allocated resource commitment if one exists. Note that utility usage will only appear in the response when the actualUsage > resourceCommitmentsUsage. Note that the resourceCommitmentUsage will always be less than or equal to the resourceCommitmentCapacity which is defined by the commitment.
The following will always hold:
utilityUsage + resourceCommitmentUsage = actualUsage
| Attributes | |
|---|---|
organizationIdUUID |
Id of the organization. |
serviceConnectionIdUUID |
Id of the service connection. |
serviceConnectionPricingIdUUID |
Id of the service connection pricing. |
utilityCoststring |
Utility cost of the record (aggregated per the period). |
utilityUsagestring |
Utility usage of the record. |
resourceCommitmentUsagestring |
The amount of usage that was counted toward the commitment capacity defined by the resource commitment. |
startDatestring |
Start date of the record in ISO 8601. |
endDatestring |
End date of the record in ISO 8601. |
usageTypestring |
Usage type of the record. |
secondaryTypestring |
Secondary type of the record. |
| Query Parameters (required) | |
|---|---|
start_dateString |
Start date (inclusive). Should have the following format YYYY-MM-DD. |
end_dateString |
End date (exclusive). Should have the following format YYYY-MM-DD. |
| Query Parameters | |
|---|---|
service_connection_idUUID |
Show usage summary for this service connection. |
include_sub_orgsboolean |
Include usage summary of all its sub-organizations. Defaults to false. |
include_costboolean |
Include the utility cost and service connection pricing id fields. Defaults to true. |
include_free_usageboolean |
Include all summary records that has no cost associated to it (i.e. utilityCost == 0). Defaults to true. |
combine_usage_typesboolean |
Sums up the utility cost per organization and service connection. The following fields are removed from the output: serviceConnectionPricingId, usageType, secondaryType, utilityUsage. |
periodString |
The period on which the aggregation is made. HOUR, DAY or PERIOD. The default is HOUR. |
include_deletedboolean |
Will find usage of an organization that may have been deleted. |
Retrieve service usage
GET /service/usage
# Retrieve customer usage
curl -X POST "https://cloudmc_endpoint/api/v2/service/usage?page=1&page_size=1" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": {
"records": [
{
"id": "a855e912f682b398379eefd5bbeffa2e:805",
"usageType": "memory_type",
"usage": 143.99833333333333,
"unit": "gibibyte-hour",
"connectionId": "081ffa1f-1531-4dd5-a7e2-070e560409ce",
"connectionName": "Edge Services",
"organizationId": "ca785487-5e22-4bac-ab01-187260b0d0cb",
"organizationName": "Cox",
"environmentId": "207ed06a-5b20-4d79-a7eb-d9ac4878519b",
"environmentName": "jdias-test-jason",
"startDate": "2022-01-01T00:00:00Z",
"endDate": "2022-01-02T00:00:00Z",
"fields": {
"PoP": "Phoenix",
"type": "Container",
"region": "NA"
},
"metricType": "GAUGE",
"metadata": {
"serviceCode": "edge-cloud-beta",
"account_id": "69b60c67-6175-4515-bb65-033108305d66",
"stackId": "cb9caf46-323f-402c-b173-742ba464e50e",
"service_account_id": "657c6671-872f-4590-8e31-a9bc6589918b",
"stackSlug": "jdias-test-jaso-7vhhr3lplg-env",
"client_id": "4e0c5f157c5d089671a57c4132205667",
"credential_id": "8b4e6d56-216b-4c70-8ce6-d283042aa3b9"
}
}
],
"metadata": {
"totalCount": 13922,
"totalPageCount": 13923,
"count": 1,
"page": 1
}
}
}
| Record Attributes | Description |
|---|---|
| id String |
The id of the record. |
| usageType String |
The type of the underlying usage. |
| usage Number |
The amount of usage within this usage records period. |
| unit String |
The unit attributed to the usage. |
| connectionId String |
The id of the connection on which this usage was generated. |
| connectionName String |
The name of the connection on which this usage was generated. |
| organizationId String |
The id of the organization on which this usage was generated. |
| organizationName String |
The name of the organization on which this usage was generated. |
| environmentId String |
The id of the environment on which this usage was generated. |
| environmentName String |
The name of the environment on which this usage was generated. |
| startDate ISO8601 Date Time |
The start date of the record (inclusive) |
| endDate ISO8601 Date Time |
The end date of the record (exclusive) |
| fields Object |
Attributes of the underlying resource that created this usage |
| metricType String |
The type of metric being summarized in this record. [COUNTER,GAUGE]. Counter accumulates over time. Gauge types indicate a particular amount of usage during record duration and fluxate up and down. |
| metadata Object |
Attributes of the underlying environment under which this usge was created. |
| Metadata Attributes | Description |
|---|---|
| total_record_count Number |
The total number of records satisfying the query. |
| total_page_count Number |
The total number of pages. |
| page_size Number |
The number of records returned on this page only. |
| page Number |
The page returned. Always the same as the page requested. |
Query Options
| Required Query Parameters | Description |
|---|---|
| start_date (inclusive) | Retrieve the usage starting from the requested date and time |
| end_date (exclusive) | Retrieve the usage up to the specific date and time |
The start_date and end_date must be an ISO8601 date time. For example 2011-12-03T10:15:30Z.
| Optional Query Parameters | Description | Default Behaviour (when not specified) |
|---|---|---|
| organization_id | Retrieve the usage of a specific organization only | All organizations the caller has visibility on |
| environment_Id | Retrieve the usage of a specific environment only | All environments the caller has visibility on |
| connection_id | Retrieve the usage of a specific connection only | All connections the caller have visibility on |
| usage_type | Retrieve the usage of a specific usage type only | All usage types |
| fields.fieldName | Retrieve the usage that matches a specific field name. Example: fields.region=EU |
No filtering of fields applied. Multiple field filters are supported for unique field names and will be applied with the AND operator. |
Paged JSON response
To retrieve data as a json response supply the application/json Accept header in your request. For example: Accept: application/json. Some query parameters apply only when retrieving a paged json response.
| Query parameters (application/json) | Description | Default Behaviour (when not specified) |
|---|---|---|
| page | The page of data to retrieve [1,...,N] | 1 |
| page_size | The size of the page to retrieve (max: 1000) | 100 |
| granularity | [YEARLY, MONTHLY, DAILY, HOURLY]. Transforms the data into the requested granularity | No transformation is made |
| next_page_token | For requests that specify a granularity, may be used to retrieve the next page of results. |
{
"records": [...],
"metadata": {
"count": 65536,
"next_page_token": "ewogICJzb3J0IjogInN0YXJ0RGF0ZSIsCiAgInZhbHVlIjogMTY1MDU1NTQ0OQp9"
}
}
Granularity Query
Note: a granularity query is expensive and may take time. Regarding JSON response, when specifying a granularity, traditional paging is not performed. Only up to 1,000 results may be returned at a time. If there are more than 1,000 results only the first 1,000 results will be returned and subsequent records maybe retrieved by specifying the next_page_token query param in the request. The token will be provided in the response as shown.
When specifying a granularity the duration between the start and end dates must be greater than or equal to the granularity specified.
CSV Response
To retrieve data as a csv response supply the text/csv Accept header in your request. For example: Accept: text/csv
List filterable fields by usage type
This endpoint returns the filterable fields for each usage type for the requested service type. Filterable fields are used when defining products.
GET service/:serviceType/filterable_fields
# Retrieve usage summary in JSON
curl "https://cloudmc_endpoint/api/v2/service/stackpath/filterable_fields" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": {
"storage_type": [
{
"field": "type",
"label": "stackpath.fields.type",
"capturable": false,
"unit": "UNIT"
}
]
}
}
| Path Parameters | |
|---|---|
serviceTypeString |
The service type to retrieve filterable fields for. |
| Attributes | |
|---|---|
fieldString |
The name of the field.. |
labelString |
The label used for the field in the UI. |
capturableboolean |
Whether the field can be used as usage for a product. |
unitString |
The unit used to measure the field. |
Note that granularity and paging (of any kind) are not supported for the CSV response type.
Monetization
Reports
Reports using the pricing v2 engine.
Get an organization report
GET /reports/organization_pricing?organization_id=:id&start_date:=end_date=&end_date=:end_date
Retrieves a list of usage grouped by currency and containing categories and their products. There is a cost sum at the currency, category and product level of granularity. Generates a report using pricing packages from the closest reseller to the organization, not including itself.
Query Parameters
| Required | |
|---|---|
start_dateString |
An ISO-8601 instant format string representing the start of the usage. This will included any usage who's usage start date is greater than, inclusively, the provided instant. |
end_dateString |
An ISO-8601 instant format string representing the end of the usage. This will include any usage who's usage end date is less than, non-inclusively, the provided instant. |
| Optional | |
|---|---|
organization_idUUID |
The organization for which you're building the report. If not passed will default to the calling user's organization. |
service_connection_idUUID |
Only return usage for the selected service connection id. |
environment_idUUID |
Only return usage for the selected environment id. Needs to be provided along with the service_connection_id. |
curl --request GET \
--url 'https://cloudmc_endpoint/api/v2/reports/organization_pricing?start_date=2021-03-30T00%3A00%3A00.000Z&end_date=2021-04-01T23%3A59%3A59.999Z'
\
--header 'MC-Api-Key: your_api_key'
{
"data": {
"currencies": [
{
"currency": "CAD",
"total": "432.00",
"categories": [
{
"name": {
"en": "Networking",
"fr": "Networking"
},
"products": [
{
"sku": "PUBLIC_IP",
"name": {
"en": "Public IP",
"fr": "Public IP"
},
"cost": "432.00",
"usage": "465.0000",
"period": "HOUR",
"unit": {
"unit": "HOUR",
"name": {}
},
"pricingTiers": [
{
"usage": "300.0000",
"price": "1.00",
"cost": "300.00"
},
{
"usage": "165.0000",
"price": "0.80",
"cost": "132.00"
}
]
}
],
"subTotal": "432.00"
}
]
}
],
"startDate": "2021-03-30T00:00:00Z",
"endDate": "2021-04-01T23:59:59.999Z",
"reportGenerated": true
}
}
| Organization Report Attributes | |
|---|---|
currenciesArray[Object] |
Returns an array of currencies for the usage. |
currencies.currencystring |
The short-name of the currency. |
currencies.totalstring |
A string containing the total of all usage. |
currencies.categoriesArray[Object] |
An array of category objects. Contains all categories that had usage for the period. |
currencies.categories.nameObject |
A map of short language codes to their translated category names. |
currencies.categories.subTotalstring |
A string with the subtotal of usage for the category. It is the summed up product usage. |
currencies.categories.productsObject |
A map of short language codes to their translated category names. |
currencies.categories.products.skustring |
A unique string representing the sku for a product. |
currencies.categories.products.nameObject |
The name object in each language for the product name. |
currencies.categories.products.coststring |
A string of the summed up total cost for the product. |
currencies.categories.products.usageObject |
A string of the summed up total usage for the product. |
currencies.categories.products.priceObject |
A string representing the average unit price over the preriod. |
currencies.categories.products.periodstring |
The period for the product capture. Possible values: HOURS, MONTH. |
currencies.categories.products.unitObject |
The unit object of the product. |
currencies.categories.products.unit.unitObject |
The unit value of the product. |
currencies.categories.products.unit.nameObject |
The name of the unit of the product in the required language. Only present when defining custom units. |
currencies.categories.products.pricingTiers Array[Object] |
The cost and usage breakdown per pricing tier configured on the product. Only pricing tiers with usage for the period are shown. |
currencies.categories.products.pricingTiers.usage string |
The total usage gathered for the given pricing tier configured on the product. |
currencies.categories.products.pricingTiers.cost string |
The total cost incurred for the given pricing tier configured on the product. |
currencies.categories.products.pricingTiers.price string |
The unit price charged per usage unit for the given pricing tier configured on the product. |
startDatestring |
An ISO-8601 instant format string representing the start of the report. |
endDatestring |
An ISO-8601 instant format string representing the end of the report. |
reportGeneratedboolean |
Whether or not a report could be generated for this time period. |
Get an organization report as a csv
GET /reports/organization_pricing?organization_id=:id&start_date:=end_date=&end_date=:end_date&language=:language¤cy=:currency
Retrieves a flat list of product with usage and cost along with other details in a csv format.
# Retrieve organizatio usage
curl --request GET \
--url "https://cloudmc_endpoint/api/v2/reports/organization_pricing?start_date=2021-07-01T00%3A00%3A00.000Z&end_date=2021-07-31T23%3A59%3A59.999Z&organization_id=a01716d0-f748-447d-94e9-60ba46753d1a&language=en¤cy=CAD" \
-H 'Accept: text/csv ' \
-H "MC-Api-Key: your_api_key"
The response is a list of products with their usage and cost, with the first line as a header, for the given organization and period.
The format of the response is a CSV with , used as the delimiter.
organization,account_id,category,sku,product_name,usage,unit,currency,cost,start_date,end_date
organizationName,12345,Compute,container_memory,Container memory,1097.272800,HOUR,CAD,2194.55,2021-07-01T00:00:00Z,2021-07-31T23:59:59.999Z
Query Parameters
| Required | |
|---|---|
start_dateString |
An ISO-8601 instant format string representing the start of the usage. This will included any usage who's usage start date is greater than the provided instant inclusively. |
end_dateString |
An ISO-8601 instant format string representing the end of the usage. This will include any usage who's usage end date is less than, non-inclusively, the provided instant. |
languageUUID |
Language to use for the report fields (but not the headers). Expected values are "en" (English), "fr" (French) or "es" (Spanish). |
| Optional | |
|---|---|
organization_idUUID |
The organization for which the report will be built. If not passed will default to the calling user's organization. |
service_connection_idUUID |
Only return usage for the selected service connection id. |
environment_idUUID |
Only return usage for the selected environment id. Needs to be provided along with the service_connection_id. |
currencyString |
The currency of usage. |
| Report Attributes | |
|---|---|
organizationString |
The organization name. |
custom_field_1String |
The organization custom field (ex: account ID). Configured in the reseller billing settings. There can be more than one custom field. |
categoryString |
The product category. |
skuString |
The SKU of the product. |
product_nameObject |
The name object in each language for the product name. |
usageString |
The total usage of the product. |
unitString |
The name of the unit of the product. |
currencyString |
The short-name of the currency. |
cost string |
The total cost of the product. |
startDatestring |
An ISO-8601 instant format string representing the start of the report. |
endDatestring |
An ISO-8601 instant format string representing the end of the report. |
Get a customer's report
GET /reports/customers?start_date:=end_date=&end_date=:end_date
Retrieves a list of all usage for the provided reseller organization and all of it's suborgs.
Query Parameters
| Required | |
|---|---|
start_dateString |
An ISO-8601 instant format string representing the start of the usage. This will included any usage who's usage start date is greater than, inclusively, the provided instant. |
end_dateString |
An ISO-8601 instant format string representing the end of the usage. This will include any usage who's usage end date is less than, non-inclusively, the provided instant. |
| Optional | |
|---|---|
organization_idUUID |
The reseller for which you're building the report. If not passed will default to the calling user's organization. This organization must be a reseller. |
service_connection_idUUID |
Only return usage for the selected service connection id. |
curl --request GET \
--url 'https://cloudmc_endpoint/api/v2/reports/customers?start_date=2021-04-01T00%3A00%3A00.000Z&end_date=2021-04-07T23%3A59%3A59.999Z' \
--header 'MC-Api-Key: your_api_key'
{
"data": {
"organizations": [
{
"id": "4b0c91a8-522a-4121-ac63-f9ae33be4eda",
"name": "JasonOrg",
"total": "5244.00",
"currency": "CAD",
"orgDeleted": "false",
"categories": [
{
"name": {
"en": "Networking",
"fr": "Networking"
},
"subTotal": "684.00"
},
{
"name": {
"en": "Disk",
"fr": "Disk"
},
"subTotal": "4560.00"
}
],
"appliedPricing": {
"id": "0495ac17-0b75-4583-af6c-c69d0d2e7289",
"name": {
"en": "Standard Pricing",
"fr": "Standard Pricing"
}
}
}
],
"reportGenerated": true,
"startDate": "2021-04-01T00:00:00Z",
"endDate": "2021-04-07T23:59:59.999Z"
}
}
| Customer Report Attributes | |
|---|---|
organizationsArray[Object] |
Returns an array of organizations for the usage. There will be one entry per organization and pricing package combination found for the time period. |
organizations.currencystring |
The short-name of the currency. |
organizations.totalstring |
A string containing the total of all usage. |
organizations.categoriesArray[Object] |
An array of category objects. Contains all categories that had usage for the period. |
organizations.categories.nameObject |
A map of short language codes to their translated category names. |
organizations.categories.subTotalstring |
A string with the subtotal of usage for the category. It is the summed up product usage. |
organizations.appliedPricingObject |
The pricing package for this organization entry. |
organizations.appliedPricing.idUUID |
The pricing package for this organization entry. |
organizations.appliedPricing.nameObject |
A map of short language codes to their translated name for the pricing package. |
startDatestring |
An ISO-8601 instant format string representing the start of the report. |
endDatestring |
An ISO-8601 instant format string representing the end of the report. |
orgDeletedboolean |
Whether or not the organization is deleted. |
metadataobject |
Additional information about the deletion event of the organization. |
reportGeneratedboolean |
Whether or not a report could be generated for this time period. |
Get a revenue taxation report
GET /reports/revenue_tax_report?billing_cycle=:billing_cycle&organization_id=:organization_id&language=:language
The response is a list of priced products, with the first line as a header, across all the customers of the given reseller and billing cycle.
The format of the response is a CSV with , used as the delimiter.
Query Parameters
| Optional | |
|---|---|
billingCycleString |
The cycle which the invoice belongs to. Format is MM-YYYY. Defaults to the latest billing cycle. |
organization_idUUID |
The reseller for which you're building the report. If not passed will default to the calling user's organization. This organization must be a reseller. |
languageUUID |
Language to use for the report fields (but not the headers). Expected values are "en" (English), "fr" (French) or "es" (Spanish). Defaults to "en". |
curl -X GET \
'https://cloudmc_endpoint/api/v2/reports/customers/revenue_tax_report?billing_cycle=:billing_cycle&organization_id=:organization_id&language=:language' \
--header 'MC-Api-Key: your_api_key'
organization,custom_field_1,custom_field_2,category,sku,usage,unit,currency,total_before_tax,tax_code,total_tax,tax_name1,tax_amount1,tax_name2,tax_amount2,invoice_number,status,due_date,credit_card_transaction_id,billing_start_date,billing_end_date,
AcmeCorp,null,null,Networking,BANDWIDTH,0.0043,GIGABYTE,USD,$0.00,SW056003,$0.00,QUEBEC QST/TVQ,$0.00,CANADA GST/TPS,$0.00,NFROFNGWHU,DRAFT,null,null,9/20/21,10/20/21,
AcmeCorp,null,null,Compute,CCM-1M02,295.935,GIGABYTE,USD,$21.90,SW056003,$3.28,QUEBEC QST/TVQ,$2.18,CANADA GST/TPS,$1.10,NFROFNGWHU,DRAFT,null,null,9/20/21,10/20/21,%
| Report Attributes | |
|---|---|
organizationString |
The organization name. |
custom_field_1String |
The organization custom field (ex: account ID). Configured in the reseller billing settings. There can be more than one custom field. |
categoryString |
The product category. |
skuString |
The SKU of the product. |
usageString |
The total usage of the product. |
unitString |
The name of the unit of the product. |
currencyString |
The short-name of the currency. |
total_before_taxString |
The total cost before taxes are applied. |
tax_codeString |
The code of the tax. |
total_taxString |
The total tax. |
tax_name1String |
The name of the tax. Depends on the tax_code, reseller billing address and customer billing address. There can be more than one tax name. |
tax_amount1String |
The amount of the tax. Depends on the tax_code, reseller billing address and customer billing address. There can be more than one tax amount. |
invoice_numberString |
The human-readable number of the invoice. |
statusString |
The status of the invoice. Possible values are: IN_PROGRESS, IN_REVIEW, ISSUED, OVERDUE, PAID, VOID, ERROR. |
due_dateString |
The date the invoice is due. |
credit_card_transaction_idString |
The confirmation number returned from the payment provider for the invoice. |
billing_start_dateString |
The billing start date of the invoice. |
billing_end_dateString |
The billing end date of the invoice. |
Notification Categories
Manage notification categories.
List notification categories
GET /content/categories
# Retrieve notification categories
curl "https://cloudmc_endpoint/api/v2/rest/content/categories?language=:language&organization_id=:organizationId" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": [
{
"organizationId": "3e824205-f507-4ffe-9891-a8addf3cf0e9",
"createdAt": "2020-10-29T14:06:50.000Z",
"translations": [
{
"language": "en",
"id": "1cea5fe9-3bfa-4eea-a9aa-8e8aa8f85346",
"text": "Test-notif-reseller",
"type": "title",
"version": 1
},
{
"language": "fr",
"id": "d4044366-2bf9-4c1f-9da5-e2e47b719714",
"text": "test-notif-reseller",
"type": "title",
"version": 1
}
],
"icon": "fa fa-envelope",
"id": "dc921a2a-16c2-4bc3-8ed6-bcb571bae241",
"version": 1,
"updatedAt": "2020-10-29T14:06:50.000Z"
}
]
}
List the notification categories configured for the organization.
| Optional Query Parameters | |
|---|---|
organization_idUUID |
The id of the organization we wish to display notification categories for. If not provided, the current user's organization id will be used. |
languageUUID |
Language of the notification categories. Expected values are "en" (English), "fr" (French) or "es" (Spanish). |
| Attributes | |
|---|---|
idUUID |
The id of the notification category. |
organizationIdUUID |
The organization id of the notification category. |
createdAtstring |
The date on which the notification category was created. |
updatedAtstring |
The date on which the notification category was updated. |
iconstring |
The icon used when displaying the notification category. |
versioninteger |
The notification category's version. |
translationsArray[Object] |
The translations of the notification category content. |
translations.languagestring |
The language of the translation. |
translations.textstring |
The content of the notification. |
translations.typestring |
The content that we are translating. For a notification category, this can only be "title". |
translations.idUUID |
The translation's id. |
translations.versioninteger |
The translation's version. |
Retrieve notification category
GET /content/categories/:id
# Retrieve notification category
curl "https://cloudmc_endpoint/api/v2/rest/content/categories/:id?language=:language" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": {
"organizationId": "3e824205-f507-4ffe-9891-a8addf3cf0e9",
"createdAt": "2020-10-29T14:06:50.000Z",
"translations": [
{
"language": "en",
"id": "1cea5fe9-3bfa-4eea-a9aa-8e8aa8f85346",
"text": "Test-notif-reseller",
"type": "title",
"version": 1
},
{
"language": "fr",
"id": "d4044366-2bf9-4c1f-9da5-e2e47b719714",
"text": "test-notif-reseller",
"type": "title",
"version": 1
}
],
"icon": "fa fa-envelope",
"id": "dc921a2a-16c2-4bc3-8ed6-bcb571bae241",
"version": 1,
"updatedAt": "2020-10-29T14:06:50.000Z"
}
}
Get a specific notification category.
| Optional Query Parameters | |
|---|---|
languageUUID |
Language of the notification categories. Expected values are "en" (English), "fr" (French) or "es" (Spanish). |
| Attributes | |
|---|---|
idUUID |
The id of the notification category. |
organizationIdUUID |
The organization id of the notification category. |
createdAtstring |
The date on which the notification category was created. |
updatedAtstring |
The date on which the notification category was updated. |
iconstring |
The icon used when displaying the notification category. |
versioninteger |
The notification category's version. |
translationsArray[Object] |
The translations of the notification category's content. |
translations.languagestring |
The language of the translation. |
translations.textstring |
The content of the notification. |
translations.typestring |
The content that we are translating. For a notification category, this can only be "title". |
translations.idUUID |
The translation's id. |
translations.versioninteger |
The translation's version. |
Create notification category
POST /content/categories/
# Create notification category
curl -X POST "https://cloudmc_endpoint/api/v2/rest/content/categories/" \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request-body"
Request body example:
{
"organizationId":"2cc1b5ba-2cfb-4bf9-9cb9-c67d34ba27b1",
"icon": "fa fa-envelope",
"translations": [
{
"language":"en",
"type":"title",
"text":"trial-ttt"
},
{
"language":"fr",
"type":"title",
"text":"trial-tt"
}
]
}
Create a notification category.
| Required | |
|---|---|
organizationIdUUID |
The organization id of the notification category. |
iconstring |
The icon used when displaying the notification category. |
translationsArray[Object] |
The translations of the notification category's content. |
translations.languagestring |
The language of the translation. |
translations.textstring |
The content of the notification. |
translations.typestring |
The content that we are translating. For a notification category, this can only be "title". |
Update notification category
PUT /content/categories/:id
# Update notification category
curl -X PUT "https://cloudmc_endpoint/api/v2/rest/content/categories/:id" \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request-body"
Request body example:
{
"id": "dc921a2a-16c2-4bc3-8ed6-bcb571bae241",
"organizationId":"3e824205-f507-4ffe-9891-a8addf3cf0e9",
"icon": "fa fa-envelope",
"translations": [
{
"language": "en",
"text": "Test-notif-reseller",
"type": "title"
},
{
"language": "fr",
"text": "test-notif-reseller",
"type": "title"
}
]
}
Update a notification category.
| Required | |
|---|---|
idUUID |
The id of the notification category. |
organizationIdUUID |
The organization id of the notification category. |
iconstring |
The icon used when displaying the notification category. |
translationsArray[Object] |
The translations of the notification category's content. |
translations.languagestring |
The language of the translation. |
translations.textstring |
The content of the notification. |
translations.typestring |
The content that we are translating. For a notification category, this can only be "title". |
| Optional | |
|---|---|
translations.idUUID |
When specified, the existing translation will be modified. If not provided, a new translation will replace the existing one. |
Delete notification category
DELETE /content/categories/:id
# Delete a notification category
curl "https://cloudmc_endpoint/api/v2/content/categories/:id" \
-X DELETE -H "MC-Api-Key: your_api_key"
Delete a notification category. You must ensure that this category has no associated notification.
Notifications
Manage notifications.
List notifications
GET /content/notifications
# Retrieve notification categories
curl "https://cloudmc_endpoint/api/v2/rest/content/notifications?language=:language&organization_id=:organiationId" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": [
{
"publishedAt": "2020-10-29T19:27:34.299Z",
"authorId": "15419d47-0ec4-47d5-8622-4fbb1948844f",
"version": 1,
"createdAt": "2020-10-29T15:04:36.134Z",
"authorLastName": "Root",
"authorFirstName": "Root",
"translations": [
{
"language": "en",
"id": "99f815c6-2aba-4462-9419-63daa67712e2",
"text": "system-notification",
"type": "title",
"version": 1
},
{
"language": "fr",
"id": "812f3b76-bc6b-4816-ace8-3e69c6e1efcd",
"text": "en français",
"type": "title",
"version": 1
},
{
"language": "en",
"id": "94c4bedb-df83-49f0-beb3-8e672e28c316",
"text": "system",
"type": "body",
"version": 1
},
{
"language": "fr",
"id": "98c1f48c-1f2b-4dc6-a43c-3f239a2473a7",
"text": "system",
"type": "body",
"version": 1
}
],
"deprecatedAt": "2020-11-03T20:57:00.000Z",
"sticky": true,
"id": "b7c6d7ca-6fef-406b-a911-bba873a99773",
"category": {
"organizationId": "1384d793-dae5-441c-8cc2-e78168c94018",
"createdAt": "2020-10-29T15:01:44.000Z",
"translations": [
{
"language": "en",
"id": "4840af1e-1d74-4b4f-bdda-6e04f4569142",
"text": "system-category",
"type": "title",
"version": 1
},
{
"language": "fr",
"id": "0bc8f49c-8f65-4319-be57-ad70cdfe144d",
"text": "en français",
"type": "title",
"version": 1
}
],
"icon": "fa fa-envelope",
"id": "2569f2cc-f1d7-4664-8439-173fedfab1c3",
"version": 1,
"updatedAt": "2020-10-29T19:28:22.000Z"
},
"splash": false,
"updatedAt": "2020-10-29T19:27:34.462Z",
"status": "published"
}
]
}
List the notifications configured for the organization.
| Optional Query Parameters | |
|---|---|
organization_idUUID |
The id of the organization we wish to display notifications for. If not provided, the current user's organization id will be used. |
languageUUID |
Language of the notification.Expected values are "en" (English), "fr" (French) or "es" (Spanish). |
| Attributes | |
|---|---|
idUUID |
The id of the notification. |
authorIdUUID |
The author's id. |
authorFirstNamestring |
The author's first name. |
authorLastNamestring |
The author's last name. |
splashboolean |
When set to true, the notification will be displayed in the home screen until it reaches its deprecated date. Only one of splash and sticky can be set to true. |
stickyboolean |
When set to true, the notification will be displayed upon logging in. Only one of splash and sticky can be set to true. |
statusstring |
The status of the notification within it's lifecycle (draft, published, deprecated). |
createdAtstring |
The date on which the notification was created. |
updatedAtstring |
The date on which the notification was updated. |
publishedAtstring |
The date on which the notification was published. |
depricatedAtstring |
The date on which the notification will be deprecated. |
versioninteger |
The notification's version. |
categoryArray[Notification Category] |
The notification category that the notification belongs to. includes: id, organizationId, createdAt, updatedAt, translations, icon, version |
translationsArray[Object] |
The translations of the notification category's content. |
translations.languagestring |
The language of the translation. |
translations.textstring |
The content of the notification. |
translations.typestring |
The content that we are translating. For a notification, this can only be "title" or "body". |
translations.idUUID |
The translation's id. |
translations.versioninteger |
The translation's version. |
Retrieve notification
GET /content/notifications/:id
# Retrieve notification category
curl "https://cloudmc_endpoint/api/v2/rest/content/notifications/:id?language=:language" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": {
"publishedAt": "2020-10-29T19:27:34.299Z",
"authorId": "15419d47-0ec4-47d5-8622-4fbb1948844f",
"version": 1,
"createdAt": "2020-10-29T15:04:36.134Z",
"authorLastName": "Root",
"authorFirstName": "Root",
"translations": [
{
"language": "en",
"id": "99f815c6-2aba-4462-9419-63daa67712e2",
"text": "system-notification",
"type": "title",
"version": 1
},
{
"language": "fr",
"id": "812f3b76-bc6b-4816-ace8-3e69c6e1efcd",
"text": "en français",
"type": "title",
"version": 1
},
{
"language": "en",
"id": "94c4bedb-df83-49f0-beb3-8e672e28c316",
"text": "system",
"type": "body",
"version": 1
},
{
"language": "fr",
"id": "98c1f48c-1f2b-4dc6-a43c-3f239a2473a7",
"text": "system",
"type": "body",
"version": 1
}
],
"deprecatedAt": "2020-11-03T20:57:00.000Z",
"sticky": true,
"id": "b7c6d7ca-6fef-406b-a911-bba873a99773",
"category": {
"organizationId": "1384d793-dae5-441c-8cc2-e78168c94018",
"createdAt": "2020-10-29T15:01:44.000Z",
"translations": [
{
"language": "en",
"id": "4840af1e-1d74-4b4f-bdda-6e04f4569142",
"text": "system-category",
"type": "title",
"version": 1
},
{
"language": "fr",
"id": "0bc8f49c-8f65-4319-be57-ad70cdfe144d",
"text": "en français",
"type": "title",
"version": 1
}
],
"icon": "fa fa-envelope",
"id": "2569f2cc-f1d7-4664-8439-173fedfab1c3",
"version": 1,
"updatedAt": "2020-10-29T19:28:22.000Z"
},
"splash": false,
"updatedAt": "2020-10-29T19:27:34.462Z",
"status": "published"
}
}
Get a specific notification.
| Optional Query Parameters | |
|---|---|
languageUUID |
Language of the notification. Expected values are "en" (English), "fr" (French) or "es" (Spanish). |
| Attributes | |
|---|---|
idUUID |
The id of the notification. |
authorIdUUID |
The author's id. |
authorFirstNamestring |
The author's first name. |
authorLastNamestring |
The author's last name. |
splashboolean |
When set to true, the notification will be displayed in the home screen until it reaches its deprecated date. Only one of splash and sticky can be set to true. |
stickyboolean |
When set to true, the notification will be displayed upon logging in. Only one of splash and sticky can be set to true. |
statusstring |
The status of the notification. |
createdAtstring |
The date on which the notification was created. |
updatedAtstring |
The date on which the notification was updated. |
publishedAtstring |
The date on which the notification was published. |
depricatedAtstring |
The date on which the notification will be deprecated. |
versioninteger |
The notification's version. |
categoryArray[Notification Category] |
The notification category that the notification belongs to. includes: id, organizationId, createdAt, updatedAt, translations, icon, version |
translationsArray[Object] |
The translations of the notification category's title. |
translations.languagestring |
The language of the translation. |
translations.textstring |
The content of the notification. |
translations.typestring |
The content that we are translating. For a notification, this can only be "title" or "body". |
translations.idUUID |
The translation's id. |
translations.versioninteger |
The translation's version. |
Create notification
POST /content/notifications/
# Create notification
curl -X POST "https://cloudmc_endpoint/api/v2/rest/content/notifications/" \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request-body"
Request body example:
{
"translations": [
{
"language": "en",
"text": "system-notification-create-no-author",
"type": "title"
},
{
"language": "fr",
"text": "en français",
"type": "title"
},
{
"language": "en",
"text": "system notification create",
"type": "body"
},
{
"language": "fr",
"text": "en français",
"type": "body"
}
],
"category": {
"id": "2569f2cc-f1d7-4664-8439-173fedfab1c3"
}
}
Create a notification.
| Required | |
|---|---|
categoryNotification Category] |
The notification category that the notification belongs to. includes: id |
translationsArray[Object] |
The translations of the notification category's content. |
translations.languagestring |
The language of the translation. |
translations.textstring |
The content of the notification. |
translations.typestring |
The content that we are translating. For a notification, this can only be "title" or "body". |
| Optional | |
|---|---|
publishedAtstring |
The date on which the notification has been/will be published. |
deprecatedAtstring |
The date on which the notification has been/will be deprecated. |
splashboolean |
When set to true, the notification will be displayed in the home screen until it reaches its deprecated date. Only one of splash and sticky can be set to true. |
stickyboolean |
When set to true, the notification will be displayed upon logging in. Only one of splash and sticky can be set to true. |
Update notification
PUT /content/notifications/:id
# Update notification
curl -X PUT "https://cloudmc_endpoint/api/v2/rest/content/notifications/:id" \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request-body"
Request body example:
{
"id":"e5412e1d-64ac-40b2-a1a1-05780584fc71",
"translations": [
{
"language": "en",
"text": "system-notification-create-no-autho",
"type": "title"
},
{
"language": "fr",
"text": "en français",
"type": "title"
},
{
"language": "en",
"text": "system notification create",
"type": "body"
},
{
"language": "fr",
"text": "en français",
"type": "body"
}
],
"category": {
"id": "dc921a2a-16c2-4bc3-8ed6-bcb571bae241"
}
}
Update a notification.
| Required | |
|---|---|
idUUID |
The id of the notification. |
categoryNotification Category] |
The notification category that the notification belongs to. includes: id |
translationsArray[Object] |
The translations of the notification category's content. |
translations.languagestring |
The language of the translation. |
translations.textstring |
The content of the notification. |
translations.typestring |
The content that we are translating. For a notification, this can only be "title" or "body". |
| Optional | |
|---|---|
publishedAtstring |
The date on which the notification has been/will be published. |
deprecatedAtstring |
The date on which the notification has been/will be deprecated. |
splashboolean |
When set to true, the notification will be displayed in the home screen until it reaches its deprecated date. Only one of splash and sticky can be set to true. |
stickyboolean |
When set to true, the notification will be displayed upon logging in. Only one of splash and sticky can be set to true. |
translations.idUUID |
When specified, the existing translation will be modified. If not provided, a new translation will replace the existing one. |
Delete notification
DELETE /content/notifications/:id
# Delete a notification category
curl "https://cloudmc_endpoint/api/v2/content/notifications/:id" \
-X DELETE -H "MC-Api-Key: your_api_key"
Delete a notification.
Product Catalogs
The product catalogs determine the product configured for a service type and optionally for specific connections.
List product catalogs
GET /product_catalogs
Retrieves a list of product catalogs configured in the system.
# Retrieve product catalog list
curl "https://cloudmc_endpoint/api/v2/product_catalogs" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": [
{
"mode": "ALL_CONNECTIONS_OF_TYPE",
"serviceType": "cloudca",
"connectionIds": [],
"name": {
"en": "fgsfdg",
"fr": "sfdg"
},
"organization": {
"name": "myOrg",
"id": "23dbae5c-24fe-4391-a8ca-f5ec4a6c2948"
},
"changes": [],
"description": {
"en": "sdfg",
"fr": "sdg"
},
"id": "5ba5df7c-1e60-4d99-869d-dd3d97826b2e",
"categories": [
{
"name": {
"en": "sdfg",
"fr": "sdfg"
},
"id": "fcd8908d-e1a0-41f2-9c38-fed1d1f77f18"
}
],
"products": [
{
"metricType": "GAUGE",
"unit": {
"unit": "HOUR",
"name": {}
},
"period": "HOUR",
"deprecated": false,
"name": {
"en": "vCPU",
"fr": "vCPU"
},
"transformer": {
"type": "PROPORTIONAL_TO_TIME"
},
"id": "342f0d9b-3c3c-456d-b853-31d713b79e72",
"attribute": "RAWUSAGE",
"source": "1",
"filters": [],
"sku": "vCPU",
"categoryId": "fcd8908d-e1a0-41f2-9c38-fed1d1f77f18"
}
]
}
]
}
| Attributes | |
|---|---|
idUUID |
The UUID of the product catalog. |
nameObject |
The name object in each language for the product catalog. |
organizationObject |
The organization the product catalog is scoped to. |
descriptionstring |
The description object in each language for the product catalog. |
modestring |
Identify the mode if it is for all service type or specific connections. Possible values: ALL_CONNECTIONS_OF_TYPE, SPECIFIC_CONNECTIONS. |
serviceTypeObject |
The service connection type the product catalog is bound to. |
connectionIdsArray[UUID] |
Array of UUID for the service connections that the catalog is bound to. |
changesArray[Object] |
Array of all changes done on the product catalog. |
categoriesArray[Object] |
The list of product categories object. |
categories.idUUID |
The id of product category object. |
categories.nameObject |
The name object in each language for the category. |
productsArray[Object] |
The list of products assigned to the catalog. |
products.metricTypestring |
The type of metrics taken. Possible values: COUNTER, GAUGE. |
products.unitObject |
The unit object of the product. |
products.unit.unitstring |
The unit value of the product. |
products.unit.nameObject |
The name of the unit of the product in the required language. Only present when defining custom units. |
products.periodstring |
The period for the product capture. Possible values: HOURS, MONTH. |
products.deprecatedboolean |
Whether or not the product is deprecated. Defaults to false. |
products.nameObject |
The name object in each language for the product name. |
products.transformerObject |
The object representing the transformation to do on the product usage. |
products.transformer.typestring |
The type of transformation to apply. Possible values: PROPORTIONAL_TO_TIME, EXPRESSION, NONE. |
products.transformer.expressionstring |
The transformation expression to apply. Only required if the type is EXPRESSION. |
products.idUUID |
The ID of the product. |
products.attributestring |
The attribute that will be used to compute usage from the service type usage. |
products.sourcestrubg |
The source of the usage to get from the service type. |
products.filtersArray[Object] |
The list of products assigned to the catalog. |
products.filters.typestring |
The type of the filter. Possible values: EXPRESSION, SIMPLE. |
products.filters.expressionstring |
The expression to filter the product in the usage generation. Only required when the type is EXPRESSION. The expression must follow the syntax of Spring Expression Language(SPEL). |
products.filters.fieldstring |
The field to filter. This is only required when type is SIMPLE. |
products.filters.operatorstring |
The operation to check on the selected field. This is only required when type is SIMPLE. Possible values: EQUAL, NOT_EQUAL, CONTAINS, STARTS_WITH, ENDS_WITH, MATCHES_REGEX, LESS_THAN, LESS_OR_EQUAL_THAN, BIGGER_THAN, BIGGER_OR_EQUAL_THAN. |
products.filters.valuestring |
The value to use in the field combined with the operation. This is only required when type is SIMPLE. |
products.skustring |
The SKU of the product. |
products.categoryIdUUID |
The UUID of the category to which belongs the product. |
Retrieve a product catalog
GET /product_catalogs/:id
Retrieve a product catalog's details.
# Retrieve a product catalog's details
curl "https://cloudmc_endpoint/api/v2/product_catalogs/03bc22bd-adc4-46b8-988d-afddc24c0cb5" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": {
"mode": "ALL_CONNECTIONS_OF_TYPE",
"serviceType": "cloudca",
"connectionIds": [],
"name": {
"en": "fgsfdg",
"fr": "sfdg"
},
"organization": {
"name": "myOrg",
"id": "23dbae5c-24fe-4391-a8ca-f5ec4a6c2948"
},
"changes": [],
"description": {
"en": "sdfg",
"fr": "sdg"
},
"id": "5ba5df7c-1e60-4d99-869d-dd3d97826b2e",
"categories": [
{
"name": {
"en": "sdfg",
"fr": "sdfg"
},
"id": "fcd8908d-e1a0-41f2-9c38-fed1d1f77f18"
}
],
"products": [
{
"metricType": "GAUGE",
"unit": {
"unit": "HOUR",
"name": {}
},
"period": "HOUR",
"deprecated": false,
"name": {
"en": "vCPU",
"fr": "vCPU"
},
"transformer": {
"type": "PROPORTIONAL_TO_TIME"
},
"id": "342f0d9b-3c3c-456d-b853-31d713b79e72",
"attribute": "RAWUSAGE",
"source": "1",
"filters": [],
"sku": "vCPU",
"categoryId": "fcd8908d-e1a0-41f2-9c38-fed1d1f77f18"
}
]
}
}
| Attributes | |
|---|---|
idUUID |
The UUID of the product catalog. |
nameObject |
The name object in each language for the product catalog. |
organizationObject |
The organization the product catalog is scoped to. |
descriptionstring |
The description object in each language for the product catalog. |
modestring |
Identify the mode if it is for all service type or specific connections. Possible values: ALL_CONNECTIONS_OF_TYPE, SPECIFIC_CONNECTIONS. |
serviceTypeObject |
The service connection type the product catalog is bound to. |
connectionIdsArray[UUID] |
Array of UUID for the service connections that the catalog is bound to. |
changesArray[Object] |
Array of all changes done on the product catalog. |
categoriesArray[Object] |
The list of product categories object. |
categories.idUUID |
The id of product category object. |
categories.nameObject |
The name object in each language for the category. |
productsArray[Object] |
The list of products assigned to the catalog. |
products.metricTypestring |
The type of metrics taken. Possible values: COUNTER, GAUGE. |
products.unitObject |
The unit object of the product. |
products.unit.unitstring |
The unit value of the product. |
products.unit.nameObject |
The name of the unit of the product in the required language. Only present when defining custom units. |
products.periodstring |
The period for the product capture. Possible values: HOURS, MONTH. |
products.deprecatedboolean |
Whether or not the product is deprecated. Deprecated products may not be updated or undeprecated. Defaults to false. |
products.nameObject |
The name object in each language for the product name. |
products.transformerObject |
The object representing the transformation to do on the product usage. |
products.transformer.typestring |
The type of transformation to apply. Possible values: PROPORTIONAL_TO_TIME, EXPRESSION, NONE. |
products.transformer.expressionstring |
The transformation expression to apply. Only required if the type is EXPRESSION. |
products.idUUID |
The ID of the product. |
products.attributestring |
The attribute that will be used to compute usage from the service type usage. |
products.sourcestrubg |
The source of the usage to get from the service type. |
products.filtersArray[Object] |
The list of products assigned to the catalog. |
products.filters.typestring |
The type of the filter. Possible values: EXPRESSION, SIMPLE. |
products.filters.expressionstring |
The expression to filter the product in the usage generation. Only required when the type is EXPRESSION. The expression must follow the syntax of Spring Expression Language(SPEL). |
products.filters.fieldstring |
The field to filter. This is only required when type is SIMPLE. |
products.filters.operatorstring |
The operation to check on the selected field. This is only required when type is SIMPLE. Possible values: EQUAL, NOT_EQUAL, CONTAINS, STARTS_WITH, ENDS_WITH, MATCHES_REGEX, LESS_THAN, LESS_OR_EQUAL_THAN, BIGGER_THAN, BIGGER_OR_EQUAL_THAN. |
products.filters.valuestring |
The value to use in the field combined with the operation. This is only required when type is SIMPLE. |
products.skustring |
The SKU of the product. |
products.categoryIdUUID |
The UUID of the category to which belongs the product. |
Create product catalog
POST /product_catalogs
Create a new product catalog.
# Creates a new product catalog
curl -X POST "https://cloudmc_endpoint/api/v2/product_catalogs" \
-H "MC-Api-Key: your_api_key"
Request body example:
{
"mode": "ALL_CONNECTIONS_OF_TYPE",
"serviceType": "cloudca",
"connectionIds": [],
"name": {
"en": "name_en",
"fr": "name_fr",
"es": "name_es"
},
"organization": {
"id": "23dbae5c-24fe-4391-a8ca-f5ec4a6c2948"
},
"description": {
"en": "beep boop",
"fr": "beep boop",
"es": "beep boop"
},
"categories": [
{
"name": {
"en": "category_en",
"fr": "category_fr",
"es": "category_es"
},
"id": "c14daee2-4678-4710-b9af-fc26fbd3c7f3"
}
],
"products": [
{
"categoryId": "c14daee2-4678-4710-b9af-fc26fbd3c7f3",
"metricType": "GAUGE",
"unit": {
"unit": "HOUR",
"name": {}
},
"period": "HOUR",
"deprecated": false,
"name": {
"en": "product_en",
"fr": "product_fr",
"es": "product_es"
},
"transformer": {
"type": "PROPORTIONAL_TO_TIME"
},
"attribute": "RAWUSAGE",
"source": "1",
"filters": [],
"sku": "product_sku"
}
]
}
The above command return JSON structured like this:
{
"data": {
"mode": "ALL_CONNECTIONS_OF_TYPE",
"serviceType": "cloudca",
"connectionIds": [],
"name": {
"en": "madeInApi",
"fr": "madeInApi",
"es": "madeInApi"
},
"organization": {
"name": "myOrg",
"id": "23dbae5c-24fe-4391-a8ca-f5ec4a6c2948"
},
"description": {
"en": "beep boop",
"fr": "beep boop",
"es": "beep boop"
},
"id": "b541a90b-afb6-44cf-8a0d-3332668bbe12",
"categories": [
{
"name": {
"en": "category_en",
"fr": "category_fr",
"es": "category_es"
},
"id": "c14daee2-4678-4710-b9af-fc26fbd3c7f3"
}
],
"products": [
{
"metricType": "GAUGE",
"unit": {
"unit": "HOUR",
"name": {}
},
"period": "HOUR",
"deprecated": false,
"name": {
"en": "product_en",
"fr": "product_fr",
"es": "product_es"
},
"transformer": {
"type": "PROPORTIONAL_TO_TIME"
},
"id": "e28f7a0a-ca4d-4840-af11-ac760bfcd42b",
"attribute": "RAWUSAGE",
"source": "1",
"filters": [],
"sku": "product_sku",
"categoryId": "c14daee2-4678-4710-b9af-fc26fbd3c7f3"
}
]
}
}
| Required | |
|---|---|
nameObject |
The name object in each language for the product catalog. |
descriptionstring |
The description object in each language for the product catalog. |
modestring |
Identify the mode if it is for all service type or specific connections. Possible values: ALL_CONNECTIONS_OF_TYPE, SPECIFIC_CONNECTIONS. |
serviceTypeObject |
The service connection type the product catalog is bound to. |
| Optional | |
|---|---|
organizationObject |
The orgnization the product catalog is scoped to. If no organization is provided, the user's organization is used by default. |
connectionIdsArray[UUID] |
Array of UUID for the service connections that the catalog is bound to. |
categoriesArray[Object] |
The list of product categories object. |
categories.idUUID |
The id of product category object. Required for each category object. |
categories.nameObject |
The name object in each language for the category. |
productsArray[Object] |
The list of products assigned to the catalog. |
products.metricTypestring |
The type of metrics taken. Possible values: COUNTER, GAUGE. |
products.unitObject |
The unit object of the product. |
products.unit.unitstring |
The unit value of the product. |
products.unit.nameObject |
The name of the unit of the product in the required language. Only present when defining custom units. |
products.periodstring |
The period for the product capture. Possible values: HOURS, MONTH. |
products.deprecatedboolean |
Whether or not the product is deprecated. Deprecated products may not be updated or undeprecated. Defaults to false. |
products.nameObject |
The name object in each language for the product name. |
products.transformerObject |
The object representing the transformation to do on the product usage. |
products.transformer.typestring |
The type of transformation to apply. Possible values: PROPORTIONAL_TO_TIME, EXPRESSION, NONE. |
products.transformer.expressionstring |
The transformation expression to apply. Only required if the type is EXPRESSION. |
products.idUUID |
The id of the product. Returned with the response. |
products.attributestring |
The source attribute that will be used to compute usage from the service type usage. |
products.sourcestrubg |
The source of the usage to get from the service type. |
products.filtersArray[Object] |
The list of products assigned to the catalog. |
products.filters.typestring |
The type of the filter. Possible values: EXPRESSION, SIMPLE. |
products.filters.expressionstring |
The expression to filter the product in the usage generation. Only required when the type is EXPRESSION. The expression must follow the syntax of Spring Expression Language(SPEL). |
products.filters.fieldstring |
The field to filter. This is only required when type is SIMPLE. |
products.filters.operatorstring |
The operation to check on the selected field. This is only required when type is SIMPLE. Possible values: EQUAL, NOT_EQUAL, CONTAINS, STARTS_WITH, ENDS_WITH, MATCHES_REGEX, LESS_THAN, LESS_OR_EQUAL_THAN, BIGGER_THAN, BIGGER_OR_EQUAL_THAN. |
products.filters.valuestring |
The value to use in the field combined with the operation. This is only required when type is SIMPLE. |
products.skustring |
The SKU of the product. |
products.categoryIdUUID |
The UUID of the category to which belongs the product. Required for each product. |
Update product catalog
PUT /product_catalogs/:id
Update an existing product catalog, including its associated categories and products.
The catalog's service type as well as the existing product SKUs cannot be edited. In addition, users may not delete categories or products. Products may be marked as deprecated. Deprecated products may not be updated or un-deprecated.
Changing a product definition affects how future usage charges will be calculated to customers. It will not be retroactively applied to records already processed. A manual rollback can be used to reprocess past usage charges with the updated product definition.
# Updates a product catalog
curl -X PUT "https://cloudmc_endpoint/api/v2/product_catalogs/b541a90b-afb6-44cf-8a0d-3332668bbe12" \
-H "MC-Api-Key: your_api_key"
Request body example:
{
"mode": "ALL_CONNECTIONS_OF_TYPE",
"connectionIds": [],
"name": {
"en": "updated_en",
"fr": "name_fr",
"es": "name_es"
},
"description": {
"en": "beep boop",
"fr": "beep boop",
"es": "beep boop"
},
"id": "b541a90b-afb6-44cf-8a0d-3332668bbe12",
"categories": [
{
"name": {
"en": "category_en",
"fr": "category_fr",
"es": "category_es"
},
"id": "c14daee2-4678-4710-b9af-fc26fbd3c7f3"
}
],
"products": [
{
"categoryId": "c14daee2-4678-4710-b9af-fc26fbd3c7f3",
"metricType": "GAUGE",
"unit": {
"unit": "HOUR",
"name": {}
},
"period": "HOUR",
"deprecated": false,
"name": {
"en": "product_en",
"fr": "product_fr",
"es": "product_es"
},
"transformer": {
"type": "PROPORTIONAL_TO_TIME"
},
"id": "e28f7a0a-ca4d-4840-af11-ac760bfcd42b",
"attribute": "RAWUSAGE",
"source": "1",
"filters": [],
}
]
}
The above command return JSON structured like this:
{
"data": {
"mode": "ALL_CONNECTIONS_OF_TYPE",
"serviceType": "cloudca",
"connectionIds": [],
"name": {
"en": "updated_en",
"fr": "name_fr",
"es": "name_es"
},
"organization": {
"name": "myOrg",
"id": "23dbae5c-24fe-4391-a8ca-f5ec4a6c2948"
},
"description": {
"en": "beep boop",
"fr": "beep boop",
"es": "beep boop"
},
"id": "b541a90b-afb6-44cf-8a0d-3332668bbe12",
"categories": [
{
"name": {
"en": "category_en",
"fr": "category_fr",
"es": "category_es"
},
"id": "c14daee2-4678-4710-b9af-fc26fbd3c7f3"
}
],
"products": [
{
"metricType": "GAUGE",
"unit": {
"unit": "HOUR",
"name": {}
},
"period": "HOUR",
"deprecated": false,
"name": {
"en": "product_en",
"fr": "product_fr",
"es": "product_es"
},
"transformer": {
"type": "PROPORTIONAL_TO_TIME"
},
"id": "e28f7a0a-ca4d-4840-af11-ac760bfcd42b",
"attribute": "RAWUSAGE",
"source": "1",
"filters": [],
"sku": "product_sku",
"categoryId": "c14daee2-4678-4710-b9af-fc26fbd3c7f3"
}
]
}
}
| Required | |
|---|---|
nameObject |
The name object in each language for the product catalog. |
descriptionstring |
The description object in each language for the product catalog. |
modestring |
Identify the mode if it is for all service type or specific connections. Possible values: ALL_CONNECTIONS_OF_TYPE, SPECIFIC_CONNECTIONS. |
categoriesArray[Object] |
The list of product categories object. |
categories.idUUID |
The id of product category object. Required for each category object. |
categories.nameObject |
The name object in each language for the category. |
productsArray[Object] |
The list of products assigned to the catalog. |
products.metricTypestring |
The type of metrics taken. Possible values: COUNTER, GAUGE. |
products.unitObject |
The unit object of the product. |
products.unit.unitstring |
The unit value of the product. |
products.unit.nameObject |
The name of the unit of the product in the required language. Only present when defining custom units. |
products.periodstring |
The period for the product capture. Possible values: HOURS, MONTH. |
products.nameObject |
The name object in each language for the product name. |
products.deprecatedboolean |
Whether or not the product is deprecated. Deprecated products may not be updated or undeprecated. Defaults to false. |
products.transformerObject |
The object representing the transformation to do on the product usage. |
products.transformer.typestring |
The type of transformation to apply. Possible values: PROPORTIONAL_TO_TIME, EXPRESSION, NONE. |
products.transformer.expressionstring |
The transformation expression to apply. Only required if the type is EXPRESSION. |
products.idUUID |
The ID of the product. |
products.attributestring |
The attribute that will be used to compute usage from the service type usage. |
products.sourcestrubg |
The source of the usage to get from the service type. |
products.filtersArray[Object] |
The list of products assigned to the catalog. |
products.filters.typestring |
The type of the filter. Possible values: EXPRESSION, SIMPLE. |
products.filters.expressionstring |
The expression to filter the product in the usage generation. Only required when the type is EXPRESSION. The expression must follow the syntax of Spring Expression Language(SPEL). |
products.filters.fieldstring |
The field to filter. This is only required when type is SIMPLE. |
products.filters.operatorstring |
The operation to check on the selected field. This is only required when type is SIMPLE. Possible values: EQUAL, NOT_EQUAL, CONTAINS, STARTS_WITH, ENDS_WITH, MATCHES_REGEX, LESS_THAN, LESS_OR_EQUAL_THAN, BIGGER_THAN, BIGGER_OR_EQUAL_THAN. |
products.filters.valuestring |
The value to use in the field combined with the operation. This is only required when type is SIMPLE. |
products.skustring |
The SKU of the product. May not be edited after product is created. |
products.categoryIdUUID |
The UUID of the category to which belongs the product. Required for each product. |
| Optional | |
|---|---|
connectionIdsArray[UUID] |
Array of UUID for the service connections that the catalog is bound to. |
Delete product catalog
DELETE /product_catalogs/:id
Delete an existing product catalog. Users may not delete a product catalog that has associated pricings.
# Deletes a specified product catalog
curl -X DELETE "https://cloudmc_endpoint/api/v2/product_catalogs/b541a90b-afb6-44cf-8a0d-3332668bbe12" \
-H "MC-Api-Key: your_api_key"
The above command(s) return(s) JSON structured like this:
{
"taskId": "c50390c7-9d5b-4af4-a2da-e2a2678a83e8",
"taskStatus": "SUCCESS"
}
| Attributes | |
|---|---|
taskId string |
The task id related to the identity provider deletion. |
taskStatus string |
The status of the operation. |
Pricings
The pricing determines the price for each product defined for a selected catalog. When prices are created, updated, or deleted with an effective date equal to or less than the current date a rollback is propagated to regenerate the affected prices.
List pricings
GET /pricings
List pricings in your organization
# List pricings
curl "https://cloudmc_endpoint/api/v2/pricings" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "73eb0d75-03b0-44e2-9cbf-9ad25dff5da5",
"name": {
"en": "Name here",
"fr": "Nom ici"
},
"description": {
"en": "Description here",
"fr": "Description ici"
},
"supportedCurrencies": [
"CAD"
],
"missingCurrenciesPricing": false,
"effectiveDate": "2020-08-31T15:43:53Z",
"productCatalogs": [
{
"id": "ea9ff508-624f-4caa-add9-4f84c20cc1a6",
...
}
],
"organization": {
"id": "52fd201e-aa82-4a27-86b3-ea9650a7fb1e"
},
"pricingProducts": [
{
"unitPrice": {
"CAD": 13
},
"product": {
"id": "dd3fcab9-5b31-4f08-9b50-ed3326bccfb4",
...
},
"cogs": {
"CAD": 10
},
"deprecated": false,
"pricingTiers": [
{
"pricingMode": "FLAT_FEE",
"lowerBound": 0.0,
"upperBound": 1000.5,
"price": {
"CAD": 999
},
"id": "9c560c79-e600-4a8b-b73b-d359a6512601"
},
{
"pricingMode": "FLAT_FEE",
"lowerBound": 1000.5,
"chunkSize": 500,
"price": {
"CAD": 999
},
"id": "accf0b65-1406-45d6-b6d8-b83c062efcd7"
}
],
"currency": "CAD",
"id": "45425fe6-beb3-4c78-be68-f82eeb3976c6"
}
]
},
]
}
| Attributes | |
|---|---|
idUUID |
The id of the pricing |
nameObject |
A map from language to name value for that language |
descriptionObject |
A map from language to description value for that language |
supportedCurrenciesList |
A list of currencies supported by the pricing |
missingCurrenciesPricingboolean |
Specifies if one of the changes is missing the prices for one or more currencies. |
effectiveDateDate |
The date at which the pricing will take effect. |
productCatalogsArray |
A list of catalogs added to the pricing |
organizationOrganization |
Organization where the pricing was created. Fields: id |
pricingProductsArray |
Products with an associated price on it |
PricedProduct
| Attributes | |
|---|---|
idUUID |
The id of the priced product |
productProduct |
The product being priced |
cogsObject |
Map from currency code to cogs |
unitPriceObject |
Map from currency code to unit price |
deprecatedBoolean |
True if priced product is deprecated |
Retrieve pricing
GET /pricings/:id
Get a pricing in your organization
# Retrieve specific pricing
curl "https://cloudmc_endpoint/api/v2/pricings/73eb0d75-03b0-44e2-9cbf-9ad25dff5da5" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data":
{
"id": "73eb0d75-03b0-44e2-9cbf-9ad25dff5da5",
"name": {
"en": "Name here",
"fr": "Nom ici"
},
"description": {
"en": "Description here",
"fr": "Description ici"
},
"supportedCurrencies": [
"CAD"
],
"missingCurrenciesPricing": false,
"effectiveDate": "2020-08-31T15:43:53Z",
"productCatalogs": [
{
"id": "ea9ff508-624f-4caa-add9-4f84c20cc1a6",
...
}
],
"organization": {
"id": "52fd201e-aa82-4a27-86b3-ea9650a7fb1e"
},
"pricingProducts": [
{
"unitPrice": {
"CAD": 13
},
"product": {
"id": "dd3fcab9-5b31-4f08-9b50-ed3326bccfb4",
...
},
"cogs": {
"CAD": 10
},
"pricingTiers": [
{
"pricingMode": "FLAT_FEE",
"lowerBound": 0.0,
"upperBound": 1000.5,
"price": {
"CAD": 999
},
"id": "9c560c79-e600-4a8b-b73b-d359a6512601"
},
{
"pricingMode": "FLAT_FEE",
"lowerBound": 1000.5,
"chunkSize": 500,
"price": {
"CAD": 999
},
"id": "accf0b65-1406-45d6-b6d8-b83c062efcd7"
}
],
"transformer": {
"type": "PROPORTIONAL_TO_TIME"
},
"deprecated": false,
"id": "0a5553f7-5ea9-432e-9a00-58fa81964422"
}
]
},
}
| Attributes | |
|---|---|
idUUID |
The id of the pricing |
nameObject |
A map from language to name value for that language |
descriptionObject |
A map from language to description value for that language |
supportedCurrenciesList |
A list of currencies supported by the pricing |
missingCurrenciesPricingboolean |
Specifies if one of the changes is missing the prices for one or more currencies. |
effectiveDateDate |
The date at which the pricing will take effect. |
productCatalogsArray |
A list of catalogs added to the pricing |
organizationOrganization |
Organization where the pricing was created. Fields: id |
pricingProductsArray |
Products with an associated price on it |
PricedProduct
| Attributes | |
|---|---|
idUUID |
The id of the priced product |
productProduct |
The product being priced |
cogsObject |
Map from currency code to cogs |
unitPriceObject |
Map from currency code to unit price |
deprecatedBoolean |
True if priced product is deprecated |
Create Pricing
POST /pricings
Create a pricing and put a price on selected products.
# Create a pricing
curl -X POST "https://cloudmc_endpoint/api/v2/pricings" \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request_body"
Request body example:
{
"name": {
"en": "Name here",
"fr": "Nom ici"
},
"description": {
"en": "Description here",
"fr": "Description ici"
},
"supportedCurrencies": [
"CAD"
],
"effectiveDate": "2020-08-31T12:00:00Z",
"organization": {
"id": "52fd201e-aa82-4a27-86b3-ea9650a7fb1e"
},
"pricingProducts": [
{
"unitPrice": {
"CAD": 13
},
"product": {
"id": "dd3fcab9-5b31-4f08-9b50-ed3326bccfb4",
},
"cogs": {
"CAD": 10
}
}
]
}
| Required | |
|---|---|
idUUID |
The id of the pricing |
nameObject |
A map from language to name value for that language |
descriptionObject |
A map from language to description value for that language |
supportedCurrenciesList |
A list of currencies supported by the pricing |
effectiveDateDate |
The date at which the pricing will take effect. |
pricingProductsArray |
Products with an associated price on it |
PricedProduct
| Required | |
|---|---|
idUUID |
The id of the priced product |
productProduct |
The product being priced |
cogsObject |
Map from currency code to cogs |
unitPriceObject |
Map from currency code to unit price |
| Optional | |
|---|---|
pricingTiers Array |
List of pricing tiers on priced product. |
PricingTier
| Attributes | |
|---|---|
idUUID |
UUID of the pricing tier. |
pricingModeEnum |
The pricing mode of the pricing tier. Must be one of "FLAT_FEE" or "PER_UNIT". |
lowerBounddouble |
The pricing tier's lower bound. |
upperBounddouble |
The pricing tier's upper bound. A null value indicates that there is no upper bound for the given tier. |
priceObject |
Map from currency code to price. Must include all supported currencies. |
chunkSizedouble |
The pricing tier's chunk size. |
# Response body example
{
"data":
{
"id": "73eb0d75-03b0-44e2-9cbf-9ad25dff5da5",
"name": {
"en": "Name here",
"fr": "Nom ici"
},
"description": {
"en": "Description here",
"fr": "Description ici"
},
"supportedCurrencies": [
"CAD"
],
"effectiveDate": "2020-08-31T12:00:00Z",
"organization": {
"id": "52fd201e-aa82-4a27-86b3-ea9650a7fb1e"
},
"pricingProducts": [
{
"unitPrice": {
"CAD": 13
},
"product": {
"id": "dd3fcab9-5b31-4f08-9b50-ed3326bccfb4",
},
"cogs": {
"CAD": 10
},
"deprecated": false,
}
]
},
}
Update Pricing
PUT /pricings/:id
Update the name and description of a pricing. If you want to modify anything else, then you can use the pricing change API.
# Update a pricing
curl -X PUT "https://cloudmc_endpoint/api/v2/pricings/73eb0d75-03b0-44e2-9cbf-9ad25dff5da5" \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request_body"
Request body example:
{
"name": {
"en": "Name here",
"fr": "Nom ici"
},
"description": {
"en": "Description here",
"fr": "Description ici"
}
}
| Required | |
|---|---|
nameObject |
A map from language to name value for that language |
descriptionObject |
A map from language to description value for that language |
Priced product
# Response body example
{
"data":
{
"id": "73eb0d75-03b0-44e2-9cbf-9ad25dff5da5",
"name": {
"en": "Name here",
"fr": "Nom ici"
},
"description": {
"en": "Description here",
"fr": "Description ici"
},
"supportedCurrencies": [
"CAD"
],
"effectiveDate": "2020-08-31T12:00:00Z",
"organization": {
"id": "52fd201e-aa82-4a27-86b3-ea9650a7fb1e"
},
"pricingProducts": [
{
"unitPrice": {
"CAD": 13
},
"product": {
"id": "dd3fcab9-5b31-4f08-9b50-ed3326bccfb4",
},
"cogs": {
"CAD": 10
},
"deprecated": false,
}
]
},
}
Delete Pricing
DELETE /pricings/:id
Delete a pricing that has no applied pricing using it.
# Update a pricing
curl -X DELETE "https://cloudmc_endpoint/api/v2/pricings/73eb0d75-03b0-44e2-9cbf-9ad25dff5da5" \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request_body"
Retrieve Effective Pricing
GET /pricings/:id
Get an effective pricing in your organization at a certain date. It will apply all the changes up-to the specified date.
# Get effective pricing
curl "https://cloudmc_endpoint/api/v2/pricings/73eb0d75-03b0-44e2-9cbf-9ad25dff5da5/effective?date=2021-01-01" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data":
{
"id": "73eb0d75-03b0-44e2-9cbf-9ad25dff5da5",
"name": {
"en": "Name here",
"fr": "Nom ici"
},
"description": {
"en": "Description here",
"fr": "Description ici"
},
"supportedCurrencies": [
"CAD"
],
"missingCurrenciesPricing": false,
"effectiveDate": "2020-08-31T15:43:53Z",
"productCatalogs": [
{
"id": "ea9ff508-624f-4caa-add9-4f84c20cc1a6",
...
}
],
"organization": {
"id": "52fd201e-aa82-4a27-86b3-ea9650a7fb1e"
},
"pricingProducts": [
{
"unitPrice": {
"CAD": 14
},
"product": {
"id": "dd3fcab9-5b31-4f08-9b50-ed3326bccfb4",
...
},
"cogs": {
"CAD": 11
},
"deprecated": false,
"id": "0a5553f7-5ea9-432e-9a00-58fa81964422"
}
]
},
}
| Query | |
|---|---|
dateDate |
The date we want the pricing on. Defaults to current date. |
| Attributes | |
|---|---|
idUUID |
The id of the pricing |
nameObject |
A map from language to name value for that language |
descriptionObject |
A map from language to description value for that language |
supportedCurrenciesList |
A list of currencies supported by the pricing |
missingCurrenciesPricingboolean |
Specifies if one of the changes is missing the prices for one or more currencies. |
effectiveDateDate |
The date at which the pricing will take effect. |
productCatalogsArray |
A list of catalogs added to the pricing |
organizationOrganization |
Organization where the pricing was created. Fields: id |
pricingProductsArray |
Products with an associated price on it |
PricedProduct
| Attributes | |
|---|---|
idUUID |
The id of the priced product |
productProduct |
The product being priced |
cogsObject |
Map from currency code to cogs |
unitPriceObject |
Map from currency code to unit price |
pricingTiersArray |
Pricing tiers of priced product. |
deprecatedBoolean |
True if priced product is deprecated |
PricingTier
| Attributes | |
|---|---|
pricingModeEnum |
The pricing mode of the pricing tier. Must be one of "FLAT_FEE" or "PER_UNIT". |
lowerBounddouble |
The pricing tier's lower bound. |
upperBounddouble |
The pricing tier's upper bound. A null value indicates that there is no upper bound for the given tier. |
priceObject |
Map from currency code to price. |
chunkSizedouble |
The pricing tier's chunk size. |
List pricing changes
GET /pricings/:id/changes
Get all changes of a specific pricing
# List pricing changes of a pricing
curl "https://cloudmc_endpoint/api/v2/pricings/73eb0d75-03b0-44e2-9cbf-9ad25dff5da5/changes" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "50a7f27e-25f3-4dda-bf07-1b4f58056ffc",
"description": "Adding a product",
"pricingDefinition": {
"id": "73eb0d75-03b0-44e2-9cbf-9ad25dff5da5"
},
"pricedProductsToAdd": [
{
"product": {
"id": "dd3fcab9-5b31-4f08-9b50-ed3326bccfb4"
},
"cogs": {
"CAD": 9
},
"unitPrice": {
"CAD": 10
}
}
],
"creationDate": "2020-09-01T18:34:43Z",
"effectiveDate": "2020-09-02T12:00:00Z",
"missingCurrencies": [],
"pricingChangeType": "ADD_PRODUCTS"
},
{
"id": "153fa103-1017-4918-a7d5-6dcd91c3de1f",
"description": "Modifying a product",
"pricingDefinition": {
"id": "73eb0d75-03b0-44e2-9cbf-9ad25dff5da5"
},
"pricedProductsToModify": [
{
"productId": "dd3fcab9-5b31-4f08-9b50-ed3326bccfb4",
"field": "unitPrice",
"currency": "CAD",
"value": 13
}
],
"creationDate": "2020-09-01T15:08:40Z",
"effectiveDate": "2020-09-02T12:00:00Z",
"missingCurrencies": [],
"pricingChangeType": "MODIFY_PRODUCTS"
},
{
"id": "920d7ee9-8771-4485-a0f2-2e122db83c32",
"description": "Removing a product",
"pricingDefinition": {
"id": "73eb0d75-03b0-44e2-9cbf-9ad25dff5da5"
},
"creationDate": "2020-09-09T17:56:36Z",
"effectiveDate": "2020-09-02T12:00:00Z",
"pricedProductsToDeprecate": [
"dd3fcab9-5b31-4f08-9b50-ed3326bccfb4"
],
"missingCurrencies": [],
"pricingChangeType": "REMOVE_PRODUCTS"
},
{
"id": "f93d8d64-b34d-4df3-be5e-4ed265fe474d",
"description": "Adding a currency",
"pricingDefinition": {
"id": "73eb0d75-03b0-44e2-9cbf-9ad25dff5da5"
},
"pricedProductsToModify": [
{
"productId": "dd3fcab9-5b31-4f08-9b50-ed3326bccfb4",
"field": "cogs",
"currency": "USD",
"value": 14
},
{
"productId": "dd3fcab9-5b31-4f08-9b50-ed3326bccfb4",
"field": "unitPrice",
"currency": "USD",
"value": 14
}
],
"currenciesToAdd": [
"USD"
],
"creationDate": "2020-09-01T18:34:43Z",
"effectiveDate": "2020-09-02T12:00:00Z",
"missingCurrencies": [],
"pricingChangeType": "ADD_CURRENCIES"
},
{
"id": "829ce268-4235-1425-d2g4-8gws49v7dg2",
"description": "Modifying a product",
"pricingDefinition": {
"id": "73eb0d75-03b0-44e2-9cbf-9ad25dff5da5"
},
"pricedProductsToModify": [
{
"productId": "dd3fcab9-5b31-4f08-9b50-ed3326bccfb4",
"field": "pricingTiers",
"pricingTiers": [
{
"lowerBound": 0,
"upperBound": 20,
"priceMode": "PER_UNIT",
"price": {
"CAD": 20,
"USD": 17
},
},
{
"lowerBound": 20,
"upperBound": null,
"priceMode": "PER_UNIT",
"price": {
"CAD": 17,
"USD": 13
},
}
],
}
],
"creationDate": "2020-09-01T15:08:40Z",
"effectiveDate": "2020-09-02T12:00:00Z",
"missingCurrencies": [],
"pricingChangeType": "MODIFY_PRODUCTS"
},
]
}
| Attributes | |
|---|---|
idUUID |
The id of the pricing |
descriptionstring |
Description of what the change is doing |
pricingDefinition.idUUID |
The pricing being modified |
pricedProductsToAddArray |
A priced product to add to the pricing. Only with ADD_PRODUCTS type. |
pricedProductsToModifyArray |
A change to a priced product in the pricing. Only with MODIFY_PRODUCTS and ADD_CURRENCIES type. |
pricedProductsToDeprecateArray |
Priced products to deprecate |
currenciesToAddArray |
Currencies to add to the pricing. Only with ADD_CURRENCIES type. |
missingCurrenciesArray |
Currencies that are missing some prices for either the unitPrice or COGS. |
pricingChangeTypestring |
Type of change to apply |
effectiveDateDate |
Date that the change should be applied |
creationDateDate |
Date that the change was created |
PricedProduct
| Attributes | |
|---|---|
product.idUUID |
The id of the product to add prices. |
cogsObject |
Map from currency code to price. Must include all currencies in effective pricing at that point. |
unitPriceObject |
Map from currency code to price. Must include all currencies in effective pricing at that point. |
pricingTiers Array |
Pricing tiers for priced product. |
PricedProductChange
| Attributes | |
|---|---|
productIdUUID |
The id of the product to modify the price. |
fieldstring |
Field to modify. Either 'cogs', 'unitPrice', or 'pricingTiers'. |
currencystring |
Currency of value to change. Only for 'cogs' or 'unitPrice'. |
valuedouble |
New price for specifified field. Only for 'cogs' or 'unitPrice'. |
pricingTiersArray |
New pricing tiers to apply to specified product (the entire tiers, not just changes). Only for 'pricingTiers'. |
PricingTier
| Attributes | |
|---|---|
pricingModeEnum |
The pricing mode of the pricing tier. Must be one of "FLAT_FEE" or "PER_UNIT". |
lowerBounddouble |
The pricing tier's lower bound. |
upperBounddouble |
The pricing tier's upper bound. A null value indicates that there is no upper bound for the given tier. |
priceObject |
Map from currency code to price. |
chunkSizedouble |
The pricing tier's chunk size. |
Add pricing change
POST /pricings/:id/changes
Add a pricing change to a pricing
# Add pricing change
curl -X POST "https://cloudmc_endpoint/api/v2/pricings/73eb0d75-03b0-44e2-9cbf-9ad25dff5da5/changes" \
-H "MC-Api-Key: your_api_key"
Request body example: Add product body
{
"description": "Adding a product",
"pricedProductsToAdd": [
{
"product": {
"id": "dd3fcab9-5b31-4f08-9b50-ed3326bccfb4"
},
"cogs": {
"CAD": 9
},
"unitPrice": {
"CAD": 10
},
"pricingTiers": [
{
"lowerBound": 0,
"upperBound": 20,
"priceMode": "PER_UNIT",
"price": {
"CAD": 20,
"USD": 17
},
},
{
"lowerBound": 20,
"upperBound": null,
"priceMode": "PER_UNIT",
"price": {
"CAD": 17,
"USD": 13
},
}
],
}
],
"effectiveDate": "2020-09-02T12:00:00Z",
"pricingChangeType": "ADD_PRODUCTS"
}
Modify product body
{
"description": "Modifying a product",
"pricedProductsToModify": [
{
"productId": "dd3fcab9-5b31-4f08-9b50-ed3326bccfb4",
"field": "unitPrice",
"currency": "CAD",
"value": 13
},
{
"productId": "dd3fcab9-5b31-4f08-9b50-ed3326bccfb4",
"field": "pricingTiers",
"pricingTiers": [
{
"lowerBound": 0,
"upperBound": 20,
"priceMode": "PER_UNIT",
"price": {
"CAD": 20,
"USD": 17
},
},
{
"lowerBound": 20,
"upperBound": null,
"priceMode": "PER_UNIT",
"price": {
"CAD": 17,
"USD": 13
},
}
],
}
],
"effectiveDate": "2020-09-02T12:00:00Z",
"pricingChangeType": "MODIFY_PRODUCTS"
}
Remove product body
{
"description": "Removing a product",
"effectiveDate": "2020-09-02T12:00:00Z",
"pricedProductsToDeprecate": [
"dd3fcab9-5b31-4f08-9b50-ed3326bccfb4"
],
"pricingChangeType": "REMOVE_PRODUCTS"
}
Add currency to pricing body
{
"description": "Adding a currency",
"pricedProductsToModify": [
{
"productId": "dd3fcab9-5b31-4f08-9b50-ed3326bccfb4",
"field": "cogs",
"currency": "USD",
"value": 14
},
{
"productId": "dd3fcab9-5b31-4f08-9b50-ed3326bccfb4",
"field": "unitPrice",
"currency": "USD",
"value": 14
},
{
"productId": "dd3fcab9-5b31-4f08-9b50-ed3326bccfb4",
"field": "pricingTiers",
"pricingTiers": [
{
"lowerBound": 0,
"upperBound": 20,
"priceMode": "PER_UNIT",
"price": {
"CAD": 20,
"USD": 17
},
},
{
"lowerBound": 20,
"upperBound": null,
"priceMode": "PER_UNIT",
"price": {
"CAD": 17,
"USD": 13
},
}
],
}
],
"currenciesToAdd": [
"USD"
],
"effectiveDate": "2020-09-02T12:00:00Z",
"pricingChangeType": "ADD_CURRENCIES"
}
Add product
| Required | |
|---|---|
descriptionstring |
Description of the change |
pricedProductsToAddArray |
A priced product to add to the pricing. |
pricingChangeTypestring |
ADD_PRODUCTS |
effectiveDateDate |
Date that the change should be applied |
Modify product prices
| Required | |
|---|---|
descriptionstring |
Description of the change |
pricedProductsToModifyArray |
A change to a priced product in the pricing. |
pricingChangeTypestring |
MODIFY_PRODUCTS |
effectiveDateDate |
Date that the change should be applied |
Remove priced product
| Required | |
|---|---|
descriptionstring |
Description of the change |
pricedProductsToDeprecateArray |
Priced products to deprecate |
pricingChangeTypestring |
REMOVE_PRODUCTS |
effectiveDateDate |
Date that the change should be applied |
Add currencies
| Required | |
|---|---|
descriptionstring |
Description of the change |
pricedProductsToModifyArray |
Prices for the new currencies for all products. |
currenciesToAddArray |
Currencies to add |
pricingChangeTypestring |
ADD_CURRENCIES |
effectiveDateDate |
Date that the change should be applied |
PricedProduct
| Attributes | |
|---|---|
product.idUUID |
The id of the product to add prices. |
cogsObject |
Map from currency code to price. Must include all currencies in effective pricing at that point. |
unitPriceObject |
Map from currency code to price. Must include all currencies in effective pricing at that point. |
pricingTiers Array |
Pricing tiers for priced product (Optional). |
PricedProductChange
| Attributes | |
|---|---|
productIdUUID |
The id of the product to modify the price. |
fieldstring |
Field to modify. Either 'cogs', 'unitPrice', or 'pricingTiers'. |
currencystring |
Currency of value to change. Only for 'cogs' or 'unitPrice'. |
valuedouble |
New price for specifified field. Only for 'cogs' or 'unitPrice'. |
pricingTiersArray |
New pricing tiers to apply to specified product (the entire tiers, not just changes). Only for 'pricingTiers'. |
PricingTier
| Attributes | |
|---|---|
pricingModeEnum |
The pricing mode of the pricing tier. Must be one of "FLAT_FEE" or "PER_UNIT". |
lowerBounddouble |
The pricing tier's lower bound. |
upperBounddouble |
The pricing tier's upper bound. A null value indicates that there is no upper bound for the given tier. |
priceObject |
Map from currency code to price. Must include all supported currencies (not just newly added ones). |
chunkSizedouble |
The pricing tier's chunk size. |
Update pricing change
PUT /pricings/:id/changes/:change_id
Update a future pricing change of a pricing
# Update a pricing change
curl -X PUT "https://cloudmc_endpoint/api/v2/pricings/73eb0d75-03b0-44e2-9cbf-9ad25dff5da5/changes/920d7ee9-8771-4485-a0f2-2e122db83c32" \
-H "MC-Api-Key: your_api_key"
See Add Pricing Change for body. You cannot change the pricingChangeType
Remove pricing change
DELETE /pricings/:id/changes/:change_id
Remove a future pricing change from a pricing
# Remove a pricing change
curl -X DELETE "https://cloudmc_endpoint/api/v2/pricings/73eb0d75-03b0-44e2-9cbf-9ad25dff5da5/changes/920d7ee9-8771-4485-a0f2-2e122db83c32" \
-H "MC-Api-Key: your_api_key"
Pricing packages
The pricing package allows the assignment of pricing to organization with a determined scope.
List pricing packages
GET /pricing_packages
Retrieves a list of pricing packages configured in the system.
# Retrieve applied pricing list
curl "https://cloudmc_endpoint/api/v2/pricing_packages" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": [
{
"pricingDefinition": {
"supportedCurrencies": [
"CAD",
"USD"
],
"organization": {
"id": "23910576-d29f-4c14-b663-31d728ff49a5"
},
"name": {
"en": "Simple pricing",
"fr": "Facturaction simple"
},
"changes": [],
"description": {},
"id": "f786b9c5-177b-4cbc-9011-331282485d05",
"effectiveDate": "2020-06-04T17:55:17Z"
},
"endDate": "2021-06-05T23:59:59.999Z",
"organization": {
"name": "System",
"id": "23910576-d29f-4c14-b663-31d728ff49a5"
},
"currency": "USD",
"id": "47c4993a-a131-4365-a427-02de95bad85b",
"creationDate": "2020-06-04T18:30:21.000Z",
"scopeQualifier": "GLOBAL",
"startDate": "2020-06-05T00:00:00Z",
"status": "ACTIVE"
}
]
}
| Attributes | |
|---|---|
idUUID |
The UUID of the pricing package. |
pricingDefinitionObject |
The pricing definition associated with the pricing package. |
pricingDefinition.idUUID |
The UUID of the pricing. |
pricingDefinition.supportedCurrenciesArray[string] |
The list of currencies associated to the pricing. |
pricingDefinition.organization.idUUID |
The UUID of the organization owning of the pricing definition. |
pricingDefinition.nameObject |
Mapped object containing the pricing name in different languages. |
pricingDefinition.descriptionObject |
Mapped object containing the pricing description in different languages. |
pricingDefinition.effectiveDatedate |
The date to which the pricing will be applicable from. |
organizationObject |
The object representing the organization owning the pricing package. |
organization.idUUID |
The UUID of the organization. |
organization.namestring |
The name of the organization. |
startDatedate |
The start date of the pricing package. |
endDatedate |
The end date of the pricing package. If it is not present, there is no end date defined. |
currencystring |
The currency associated to the pricing package. |
scopeQualifierstring |
Scope qualifier of the pricing package. Possible values are : GLOBAL, ORG_TOPLEVEL, ORG_SUBS, ORG_BASE, ORG_TREE. |
scopeOrganizationObject |
The organization to which the scope is applied to. |
scopeOrganization.idUUID |
The UUID of the organization. |
scopeOrganization.namestring |
The name of the organization. |
creationDateObject |
The date the pricing package was created. |
statusstring |
The status of the pricing package. Possible values are : ACTIVE, EXPIRED, FUTURE. |
Retrieve a pricing package
GET /pricing_packages/:id
Retrieve a pricing package's details.
# Retrieve an applied pricing
curl "https://cloudmc_endpoint/api/v2/pricing_packages/03bc22bd-adc4-46b8-988d-afddc24c0cb5" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": {
"pricingDefinition": {
"supportedCurrencies": [
"CAD",
"USD"
],
"organization": {
"id": "23910576-d29f-4c14-b663-31d728ff49a5"
},
"name": {
"en": "Simple pricing",
"fr": "Facturaction simple"
},
"changes": [],
"description": {},
"id": "f786b9c5-177b-4cbc-9011-331282485d05",
"effectiveDate": "2020-06-04T17:55:17Z"
},
"endDate": "2021-06-05T23:59:59.999Z",
"organization": {
"name": "System",
"id": "23910576-d29f-4c14-b663-31d728ff49a5"
},
"currency": "USD",
"id": "47c4993a-a131-4365-a427-02de95bad85b",
"creationDate": "2020-06-04T18:30:21.000Z",
"scopeQualifier": "GLOBAL",
"startDate": "2020-06-05T00:00:00Z",
"status": "ACTIVE"
}
}
| Attributes | |
|---|---|
idUUID |
The UUID of the pricing package. |
pricingDefinitionObject |
The pricing definition associated with the pricing package. |
pricingDefinition.idUUID |
The UUID of the pricing. |
pricingDefinition.supportedCurrenciesArray[string] |
The list of currencies associated to the pricing. |
pricingDefinition.organization.idUUID |
The UUID of the organization owning of the pricing definition. |
pricingDefinition.nameObject |
Mapped object containing the pricing name in different languages. |
pricingDefinition.descriptionObject |
Mapped object containing the pricing description in different languages. |
pricingDefinition.effectiveDatedate |
The date to which the pricing will be applicable from. |
organizationObject |
The object representing the organization owning the pricing package. |
organization.idUUID |
The UUID of the organization. |
organization.namestring |
The name of the organization. |
startDatedate |
The start date of the pricing package. |
endDatedate |
The end date of the pricing package. If it is not present, there is no end date defined. |
currencystring |
The currency associated to the pricing package. |
scopeQualifierstring |
Scope qualifier of the pricing package. Possible values are : GLOBAL, ORG_TOPLEVEL, ORG_SUBS, ORG_BASE, ORG_TREE. |
scopeOrganizationObject |
The organization to which the scope is applied to. |
scopeOrganization.idUUID |
The UUID of the organization. |
scopeOrganization.namestring |
The name of the organization. |
creationDateObject |
The date the pricing package was created. |
statusstring |
The status of the pricing package. Possible values are : ACTIVE, EXPIRED, FUTURE. |
Create pricing package
POST /pricing_packages
Create a new pricing package. If an organization does not have a default pricing package assigned to it, then the first time a pricing package is created under that organization the billing settings will be automatically updated.
# Creates a new pricing
curl -X POST "https://cloudmc_endpoint/api/v2/pricing_packages" \
-H "MC-Api-Key: your_api_key"
Request body example:
{
"pricingDefinition": {
"id": "f786b9c5-177b-4cbc-9011-331282485d05"
},
"organization": {
"id": "23910576-d29f-4c14-b663-31d728ff49a5"
},
"currency": "USD",
"scopeQualifier": "GLOBAL",
"startDate": "2020-06-05T00:00:00Z",
"endDate": "2021-06-05T23:59:59.999Z"
}
The above command return JSON structured like this:
{
"data": {
"pricingDefinition": {
"name": {},
"changes": [],
"description": {},
"id": "f786b9c5-177b-4cbc-9011-331282485d05"
},
"endDate": "2021-06-05T23:59:59.999Z",
"organization": {
"id": "23910576-d29f-4c14-b663-31d728ff49a5"
},
"currency": "USD",
"id": "8bb5e457-41c3-410b-aced-b9c694ff141a",
"creationDate": "2020-06-04T19:31:31.178Z",
"scopeQualifier": "GLOBAL",
"startDate": "2020-06-05T00:00:00Z"
}
}
| Required | |
|---|---|
organization.id UUID |
The UUID of the organization the pricing package belongs to. |
pricingDefinition.id UUID |
the UUID of the pricing that will be used in the pricing package. |
scopeQualifier string |
The scope qualifier for the pricing package. Possible values are : ORG_BASE, ORG_TREE, ORG_SUB, ORG_TOPLEVEL, GLOBAL. |
currency String |
The currency used for the pricing package. The value is a ISO 4217 currency code that is part of the pricing selected. |
startDate Date |
The start date for the pricing package. |
| Optional | |
|---|---|
endDate Date |
The end date for the pricing package. |
scopeOrganization.id UUID |
The UUID of the organization that the scope is targeting. Only required for scopes : ORG_BASE, ORG_TREE, ORG_SUBS. |
Update pricing package
PUT /pricing_packages/:id
Update a pricing package. Updates to the pricing, the scope, start date and end date may cause charges to be rolled back.
# Update an applied pricing
curl -X PUT "https://cloudmc_endpoint/api/v2/pricing_packages/8bb5e457-41c3-410b-aced-b9c694ff141a" \
-H "MC-Api-Key: your_api_key"
Request body example:
{
"pricingDefinition": {
"id": "f786b9c5-177b-4cbc-9011-331282485d05"
},
"organization": {
"id": "23910576-d29f-4c14-b663-31d728ff49a5"
},
"currency": "USD",
"scopeQualifier": "ORG_BASE",
"scopeOrganization": {
"id": "d2e467f8-3a33-441a-b074-aec960758452"
},
"startDate": "2020-06-05T00:00:00Z",
"endDate": "2021-06-05T23:59:59.999Z"
}
The above command return JSON structured like this:
{
"data": {
"pricingDefinition": {
"supportedCurrencies": [
"CAD",
"USD"
],
"organization": {
"id": "23910576-d29f-4c14-b663-31d728ff49a5"
},
"name": {
"en": "my-pricing",
"fr": "mon-pricing"
},
"changes": [],
"description": {},
"id": "f786b9c5-177b-4cbc-9011-331282485d05",
"effectiveDate": "2020-05-06T00:00:00Z"
},
"endDate": "2021-06-05T23:59:59.999Z",
"organization": {
"name": "Systemer",
"id": "52fd201e-aa82-4a27-86b3-ea9650a7fb1e"
},
"currency": "CAD",
"id": "d08b9332-d26e-42fe-b272-3071f2d64839",
"creationDate": "2020-09-08T17:44:18.000Z",
"scopeQualifier": "ORG_BASE",
"scopeOrganization": {
"id": "d2e467f8-3a33-441a-b074-aec960758452",
"name": "scoped-organization",
},
"startDate": "2020-06-05T00:00:00Z"
}
}
| Required | |
|---|---|
organization.id UUID |
The UUID of the organization the pricing package belongs to. |
pricingDefinition.id UUID |
the UUID of the pricing that will be used in the pricing package. |
scopeQualifier string |
The scope qualifier for the pricing package. Possible values are : ORG_BASE, ORG_TREE, ORG_SUB, ORG_TOPLEVEL, GLOBAL. |
currency String |
The currency used for the pricing package. The value is a ISO 4217 currency code that is part of the pricing selected. |
startDate Date |
The start date for the pricing package. |
| Optional | |
|---|---|
endDate Date |
The end date for the pricing package. |
scopeOrganization.id UUID |
The UUID of the organization that the scope is targeting. Only required for scopes : ORG_BASE, ORG_TREE, ORG_SUBS. |
Delete pricing package
DELETE /pricing_packages/:id
Delete an existing pricing package. Deleting a pricing package that is ACTIVE or EXPIRED may cause charges to be rolled back.
curl -X DELETE "https://cloudmc_endpoint/api/v2/pricing_packages/d08b9332-d26e-42fe-b272-3071f2d64839" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"taskId": "85df8dfb-b904-42dc-bb76-4824e6b50c83",
"taskStatus": "SUCCESS"
}
Rollbacks
Rollbacks enable service providers to reprocess usage data from the past. Currently the only supported rollback type REPROCESS uses existing collected usage metrics and reprocesses it through the monetization engine. The most current effective pricing configuration will be used to price these records.
List rollback triggers
GET /rollbacks
Retrives a list of rollback triggers for a reseller.
Note: You must have the Reseller pricing permission on the target reseller. If the caller does not have the correct permissions or the reseller with the ID provided does not exist then a
404 Not Foundresponse will be returned. Theorganization_idquery parameter is optional. If not present, it will default to the caller's organization.
# Retrieve rollback triggers
curl "https://cloudmc_endpoint/api/v2/rollbacks?organization_id=23910576-d29f-4c14-b663-31d728ff49a5" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": [
{
"createdDate": "2022-01-06T17:43:55Z",
"resetDate": "2022-01-06",
"rollbacks": [
{
"resetDate": "2022-01-06",
"organization": {
"name": "Operator",
"id": "1b47df69-6458-4ea6-8c4b-2894b3f7ec00"
},
"id": 28428,
"state": "COMPLETED",
"serviceConnection": {
"serviceCode": "swiftstack-aaaa",
"name": "Object Storage",
"id": "4fa42796-6b93-4d9f-b5f7-34c4d1c796ea",
"type": "swiftstack"
}
},
{
"resetDate": "2022-01-06",
"organization": {
"name": "WhitePages",
"id": "5f07f7d6-8eaf-418e-87a1-8dc063135003"
},
"id": 28429,
"state": "SCHEDULED",
"serviceConnection": {
"serviceCode": "stackpath-aaaa",
"name": "Edge Services",
"id": "2d468fc0-434d-49a7-9739-e8d4fda0c488",
"type": "stackpath"
}
}
],
"organization": {
"name": "Operator",
"id": "1b47df69-6458-4ea6-8c4b-2894b3f7ec00"
},
"name": "Rollback January",
"description": "This is a description",
"id": "006980fe-6ee5-4c04-a0aa-df04acab54f9",
"state": "SCHEDULED",
"type": "REPROCESS"
}
]
}
| Attributes | |
|---|---|
idUUID |
The UUID of the rollback trigger provider. |
namestring |
The name of the rollback. |
descriptionstring |
The description of the rollback (optional). |
organization.idUUID |
The UUID of the organization (reseller) responsble for creating the rollback trigger |
typestring |
The type of the rollback: Possible values are REPROCESS, RECOLLECT. |
The REPROCESS type is only available to users with operator permission. |
|
The RECOLLECT type is available to connection owners and operators. |
|
stateenum |
The state of the rollback. Possible values are: COMPLETED, SCHEDULED & PENDING. |
createdDatestring |
The date the rollback trigger was created. |
resetDatestring |
The date in which we want to start the rollback (inclusive). |
rollbacksArray |
A list of rollbacks scoped to a service connection and organization. |
Get a rollback trigger
GET /rollbacks/:id
Retrives a rollback trigger's details.
Note: You must have the Reseller pricing permission on the target reseller. If the caller does not have the correct permissions or the reseller with the ID provided does not exist then a
404 Not Foundresponse will be returned.
# Retrieve rollback triggers
curl "https://cloudmc_endpoint/api/v2/rollbacks/23910576-d29f-4c14-b663-31d728ff49a5" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": {
"createdDate": "2022-01-10T17:06:10Z",
"resetDate": "2022-01-10",
"rollbacks": [
{
"resetDate": "2022-01-10",
"organization": {
"name": "WhitePages",
"id": "5f07f7d6-8eaf-418e-87a1-8dc063135003"
},
"id": 28446,
"state": "COMPLETED",
"serviceConnection": {
"serviceCode": "swiftstack-aaaa",
"name": "Object Storage",
"id": "4fa42796-6b93-4d9f-b5f7-34c4d1c796ea",
"type": "swiftstack"
}
}
],
"organization": {
"name": "Operator",
"id": "1b47df69-6458-4ea6-8c4b-2894b3f7ec00"
},
"name": "Rollback",
"description": "Fix bug in pipeline for date conversion",
"id": "6064e10e-a105-423a-b724-ba470bf42e79",
"state": "COMPLETED",
"type": "REPROCESS"
}
}
| Attributes | |
|---|---|
idUUID |
The UUID of the rollback trigger provider. |
namestring |
The name of the rollback. |
descriptionstring |
The description of the rollback (optional). |
organization.idUUID |
The UUID of the organization (reseller) responsble for creating the rollback trigger. |
typestring |
The type of the rollback: Possible values are REPROCESS, RECOLLECT. |
The REPROCESS type is only available to users with operator permission. |
|
The RECOLLECT type is available to connection owners and operators. |
|
stateenum |
The state of the rollback. Possible values are: COMPLETED, SCHEDULED & PENDING. |
createdDatestring |
The date the rollback trigger was created. |
resetDatestring |
The date in which we want to start the rollback (inclusive). |
rollbacksArray |
A list of rollbacks scoped to a service connection and organization that were generated based on the rollback trigger configuration. |
Create a rollback trigger
POST /rollbacks
Creates a rollback which will result in reprocessing of usage for the given request body. The Rollback API supports two types of rollback: REPROCESS and RECOLLECT.
The REPROCESS rollback re-processes existing usage, previously collected from the backend service, in the monetization engine. The latest pricing configuration will be used on these records.
The API body supports targeting a set of service connections and organizations as well as the date from which the rollback should begin the reprocess. If usage is not found for the requested date and organization and service connection pair the API will default to the earliest available usage for the pair. If there is no previous usage for the organization and connection, no rollback will be generated for this pair.
The RECOLLECT rollback type can be used by connection owners to retrigger the collection of usage from the underlying backend service. The RECOLLECT rollback is limitted by the retention period of underlying usage of the targeted service. If, for example, the targeted service only stores 60 days of usage the earliest reset date will be 60 days before today. A recollect rollback impacts all assigned organizations of the selected service connection.
Note: this operation will take time and the state of the rollbacks will update once the operation is complete.
Once a rollback is complete the usage on the customer usage reports after the selected reset date should reflect the latest pricing configuration applied. Rollbacks of all types will not impact issued, paid or overdue invoices. Only invoices that are not in the hands of customers will be regenerated.
Note: You must have the Reseller pricing permission on the target reseller. If the caller does not have the correct permissions or the reseller with the ID provided does not exist then a
404 Not Foundresponse will be returned.
# Retrieve rollback triggers
curl "https://cloudmc_endpoint/api/v2/rollbacks/23910576-d29f-4c14-b663-31d728ff49a5" \
-H "MC-Api-Key: your_api_key"
Request body example:
{
"name": "Rollback - Object Storage",
"description": "This rollback correct API errors from the service",
"type": "REPROCESS",
"organization": {
"id": "1b47df69-6458-4ea6-8c4b-2894b3f7ec00"
},
"resetDate": "2022-01-10",
"serviceConnectionIds": ["4fa42796-6b93-4d9f-b5f7-34c4d1c796ea"],
"organizationIds": ["5f07f7d6-8eaf-418e-87a1-8dc063135003"]
}
The above command returns a JSON structured like this:
{
"data": {
"resetDate": "2022-01-10",
"rollbacks": [
{
"resetDate": "2022-01-10",
"organization": {
"name": "WhitePages",
"id": "5f07f7d6-8eaf-418e-87a1-8dc063135003"
},
"id": 28447,
"state": "SCHEDULED",
"serviceConnection": {
"serviceCode": "swiftstack-aaaa",
"name": "Object Storage",
"id": "4fa42796-6b93-4d9f-b5f7-34c4d1c796ea",
"type": "swiftstack"
}
}
],
"organization": {
"id": "1b47df69-6458-4ea6-8c4b-2894b3f7ec00"
},
"name": "Rollback - Object Storage",
"description": "This rollback correct API errors from the service",
"id": "eb484aea-cf19-4db1-8329-507d8a0d5c17",
"state": "SCHEDULED",
"type": "REPROCESS"
}
}
| Attributes | |
|---|---|
idUUID |
The UUID of the rollback trigger provider. |
namestring |
The name of the rollback. |
descriptionstring |
The description of the rollback (optional). |
organization.idUUID |
The UUID of the organization (reseller) responsble for creating the rollback trigger. |
typestring |
The type of the rollback: Possible values are REPROCESS, RECOLLECT. |
The REPROCESS type is only available to users with operator permission. |
|
The RECOLLECT type is available to connection owners and operators. |
|
resetDatestring |
The date in which we want to start the rollback (inclusive). |
organizationIdsArray |
The list of targeted organization IDs to apply the rollback. |
serviceConnectionIdsArray |
The list of affected service connection IDs to apply the rollback. |
Invoices
Note: Creating, deleting and updating invoices is not supported.
Get customer invoices by reseller ID
GET /invoices/find/:reseller_id/customer_invoices
Retrieve a list of invoices belonging to the customers of the reseller specified.
# Retrieve customer invoices list
curl "https://cloudmc_endpoint/api/v2/invoices/find/efd32752-c6f2-45cf-b494-cc6be8a45845/customer_invoices?includeAllSubOrgs=false&billingCycle=07-2021" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": [
{
"createdDate": "2021-11-22T17:22:49Z",
"billingCycle": {
"id": "7c10604c-3045-40ef-9890-1bd5a23d5a7b"
},
"organization": {
"name": "System",
"id": "c869e848-6fb3-4850-af3d-42c5666f2c78"
},
"invoiceId": "X5GDVRKGCY",
"id": "504735ce-cdc1-4adf-b59c-b4e43d1eefa4",
"detail": {
"adjustments": [
{
"amount": -41650.89,
"dailyDeltas": {
"2021-10-06": 0.0,
"2021-10-07": -1352.01792,
"2021-10-08": -899.184845,
"2021-10-02": -422.4,
"2021-10-03": -422.4,
"2021-10-04": -686.35776,
"2021-10-05": -2015.18592,
"2021-09-30": -422.4,
"2021-10-01": -422.4,
"2021-09-25": -422.4,
"2021-09-28": -422.4,
"2021-09-29": -422.4,
"2021-09-26": -422.4,
"2021-09-27": -422.4
},
"before": 189322.23,
"after": 147671.34,
"source": {
"endDate": "2021-10-15",
"subtype": "",
"scope": "ALL_PRODUCTS",
"typeString": "PERCENTAGE",
"discount": {
"discountedProducts": {},
"type": "PERCENTAGE",
"packageDiscount": 22.0,
"referenceId": "9b245d40-ba94-4e05-af51-89979d37fb29",
"subtype": "",
"discountedCategories": {},
"scope": "ALL_PRODUCTS",
"name": {
"en": "discount",
"fr": "escompte"
},
"id": "9b245d40-ba94-4e05-af51-89979d37fb29",
"credit": false,
"startDate": "2021-05-08T00:00:00Z"
},
"discountId": "9b245d40-ba94-4e05-af51-89979d37fb29",
"type": "PERCENTAGE",
"startDate": "2021-09-15",
"referenceId": "9b245d40-ba94-4e05-af51-89979d37fb29"
},
"type": "PERCENTAGE"
},
{
"amount": 0.0,
"dailyDeltas": {
"2021-09-25": 0.0
},
"before": 147671.34,
"after": 147671.34,
"source": {
"endDate": "2021-10-15",
"subtype": "",
"scope": "ALL_PRODUCTS",
"typeString": "CREDIT",
"discount": {
"discountedProducts": {},
"type": "CREDIT",
"packageDiscount": 250000.0,
"cutoffDate": "2021-09-27T00:00:00Z",
"referenceId": "532067ee-c194-4463-b5a1-a161e5c9388c",
"durationDays": 90,
"subtype": "",
"discountedCategories": {},
"scope": "ALL_PRODUCTS",
"name": {
"en": "bbbb",
"fr": "bb"
},
"id": "532067ee-c194-4463-b5a1-a161e5c9388c",
"credit": true,
"startDate": "2021-05-08T00:00:00Z"
},
"used": {
"packageDiscount": 0.0
},
"discountId": "532067ee-c194-4463-b5a1-a161e5c9388c",
"type": "CREDIT",
"startDate": "2021-09-15",
"remaining": {
"discountedProducts": {},
"discountedCategories": {},
"packageDiscount": 0.0
},
"referenceId": "532067ee-c194-4463-b5a1-a161e5c9388c"
},
"type": "CREDIT"
}
],
"adjustmentAggregations": [
{
"scopedBefore": 189322.23,
"scopedAmount": -41650.89,
"subtype": "",
"before": 251748.98,
"cumulativeAmount": -104077.64,
"after": 147671.34,
"type": "PERCENTAGE",
"scopedAfter": 147671.34
},
{
"scopedBefore": 147671.34,
"scopedAmount": 0.0,
"subtype": "",
"before": 147671.34,
"cumulativeAmount": 0.0,
"after": 147671.34,
"type": "CREDIT",
"scopedAfter": 147671.34
}
],
"endDate": "2021-10-15T00:00:00Z",
"inclusiveEndDate": "2021-10-14T00:00:00Z",
"subTotal": 147671.34,
"dateToSubTotalCost": {
"2021-10-06": 34144.890624,
"2021-10-07": 32116.48128,
"2021-10-08": 21359.336693999998,
"2021-10-02": 1497.6,
"2021-10-03": 1497.6,
"2021-10-04": 12766.995072,
"2021-10-05": 33805.234943999996,
"2021-09-30": 1497.6,
"2021-10-01": 1497.6,
"2021-09-25": 1497.6,
"2021-09-28": 1497.6,
"2021-09-29": 1497.6,
"2021-09-26": 1497.6,
"2021-09-27": 1497.6
},
"dateToTotalCost": {
"2021-10-06": 34144.890624,
"2021-10-07": 32116.48128,
"2021-10-08": 21359.336693999998,
"2021-10-02": 1497.6,
"2021-10-03": 1497.6,
"2021-10-04": 12766.995072,
"2021-10-05": 33805.234943999996,
"2021-09-30": 1497.6,
"2021-10-01": 1497.6,
"2021-09-25": 1497.6,
"2021-09-28": 1497.6,
"2021-09-29": 1497.6,
"2021-09-26": 1497.6,
"2021-09-27": 1497.6
},
"total": 147671.34,
"currency": "CAD",
"categories": [
{
"dateToTotalCost": {
"2021-10-06": 34144.890624,
"2021-10-07": 32116.48128,
"2021-10-08": 21359.336693999998,
"2021-10-02": 1497.6,
"2021-10-03": 1497.6,
"2021-10-04": 12766.995072,
"2021-10-05": 33805.234943999996,
"2021-09-30": 1497.6,
"2021-10-01": 1497.6,
"2021-09-25": 1497.6,
"2021-09-28": 1497.6,
"2021-09-29": 1497.6,
"2021-09-26": 1497.6,
"2021-09-27": 1497.6
},
"total": 147671.34,
"adjustments": [
{
"itemId": "950d5a79-f6df-4770-995a-5144e6feb6b0",
"amount": -47330.56,
"dailyDeltas": {
"2021-10-06": 0.0,
"2021-10-07": -1536.384,
"2021-10-08": -1021.80096,
"2021-10-02": -480.0,
"2021-10-03": -480.0,
"2021-10-04": -779.952,
"2021-10-05": -2289.984,
"2021-09-30": -480.0,
"2021-10-01": -480.0,
"2021-09-25": -480.0,
"2021-09-28": -480.0,
"2021-09-29": -480.0,
"2021-09-26": -480.0,
"2021-09-27": -480.0
},
"before": 236652.79,
"after": 189322.23,
"source": {
"endDate": "2021-10-15",
"subtype": "",
"scope": "CATEGORIES",
"typeString": "PERCENTAGE",
"discount": {
"discountedProducts": {},
"type": "PERCENTAGE",
"referenceId": "6ee154d1-4318-47bb-bb18-2e605c227889",
"subtype": "",
"discountedCategories": {
"950d5a79-f6df-4770-995a-5144e6feb6b0": 20
},
"scope": "CATEGORIES",
"name": {
"en": "compute-20-percent",
"fr": "compute-20-percent"
},
"id": "6ee154d1-4318-47bb-bb18-2e605c227889",
"credit": false,
"startDate": "2021-05-08T00:00:00Z"
},
"discountId": "6ee154d1-4318-47bb-bb18-2e605c227889",
"type": "PERCENTAGE",
"startDate": "2021-09-15",
"referenceId": "6ee154d1-4318-47bb-bb18-2e605c227889"
},
"type": "PERCENTAGE"
},
{
"itemId": "950d5a79-f6df-4770-995a-5144e6feb6b0",
"amount": -41650.89,
"dailyDeltas": {
"2021-10-06": 0.0,
"2021-10-07": -1352.01792,
"2021-10-08": -899.184845,
"2021-10-02": -422.4,
"2021-10-03": -422.4,
"2021-10-04": -686.35776,
"2021-10-05": -2015.18592,
"2021-09-30": -422.4,
"2021-10-01": -422.4,
"2021-09-25": -422.4,
"2021-09-28": -422.4,
"2021-09-29": -422.4,
"2021-09-26": -422.4,
"2021-09-27": -422.4
},
"before": 189322.23,
"after": 147671.34,
"source": {
"endDate": "2021-10-15",
"subtype": "",
"scope": "ALL_PRODUCTS",
"typeString": "PERCENTAGE",
"discount": {
"discountedProducts": {},
"type": "PERCENTAGE",
"packageDiscount": 22.0,
"referenceId": "9b245d40-ba94-4e05-af51-89979d37fb29",
"subtype": "",
"discountedCategories": {},
"scope": "ALL_PRODUCTS",
"name": {
"en": "discount",
"fr": "escompte"
},
"id": "9b245d40-ba94-4e05-af51-89979d37fb29",
"credit": false,
"startDate": "2021-05-08T00:00:00Z"
},
"discountId": "9b245d40-ba94-4e05-af51-89979d37fb29",
"type": "PERCENTAGE",
"startDate": "2021-09-15",
"referenceId": "9b245d40-ba94-4e05-af51-89979d37fb29"
},
"type": "PERCENTAGE"
}
],
"adjustmentAggregations": [
{
"scopedBefore": 236652.79,
"scopedAmount": -88981.45,
"subtype": "",
"before": 251748.98,
"cumulativeAmount": -104077.64,
"after": 147671.34,
"type": "PERCENTAGE",
"scopedAfter": 147671.34
}
],
"name": {
"en": "compute",
"fr": "dancer"
},
"subTotal": 147671.34,
"dateToSubTotalCost": {
"2021-10-06": 34144.890624,
"2021-10-07": 32116.48128,
"2021-10-08": 21359.336693999998,
"2021-10-02": 1497.6,
"2021-10-03": 1497.6,
"2021-10-04": 12766.995072,
"2021-10-05": 33805.234943999996,
"2021-09-30": 1497.6,
"2021-10-01": 1497.6,
"2021-09-25": 1497.6,
"2021-09-28": 1497.6,
"2021-09-29": 1497.6,
"2021-09-26": 1497.6,
"2021-09-27": 1497.6
},
"categoryId": "950d5a79-f6df-4770-995a-5144e6feb6b0",
"products": [
{
"adjustments": [],
"adjustmentAggregations": [
{
"subtype": "",
"before": 49740.6,
"cumulativeAmount": -18702.47,
"after": 31038.13,
"type": "PERCENTAGE"
}
],
"productId": "1f656184-df81-47c7-964f-eb9e27743d7b",
"usage": 497.406048,
"pricingTiers": [],
"subTotal": 31038.13,
"dateToSubTotalCost": {
"2021-10-06": 0.0,
"2021-10-07": 4793.51808,
"2021-10-08": 3188.018995,
"2021-10-02": 1497.6,
"2021-10-03": 1497.6,
"2021-10-04": 2433.450239999999,
"2021-10-05": 7144.75008,
"2021-09-30": 1497.6,
"2021-10-01": 1497.6,
"2021-09-25": 1497.6,
"2021-09-28": 1497.6,
"2021-09-29": 1497.6,
"2021-09-26": 1497.6,
"2021-09-27": 1497.6
},
"taxCode": "SW056003",
"dateToTotalCost": {
"2021-10-06": 0.0,
"2021-10-07": 4793.51808,
"2021-10-08": 3188.018995,
"2021-10-02": 1497.6,
"2021-10-03": 1497.6,
"2021-10-04": 2433.450239999999,
"2021-10-05": 7144.75008,
"2021-09-30": 1497.6,
"2021-10-01": 1497.6,
"2021-09-25": 1497.6,
"2021-09-28": 1497.6,
"2021-09-29": 1497.6,
"2021-09-26": 1497.6,
"2021-09-27": 1497.6
},
"total": 31038.13,
"unit": {
"unit": "UNIT",
"name": {}
},
"price": "100.000000",
"name": {
"en": "specification",
"fr": "specification"
},
"sku": "SPEC_PRODUCT",
"categoryId": "950d5a79-f6df-4770-995a-5144e6feb6b0"
},
{
"adjustments": [],
"adjustmentAggregations": [
{
"subtype": "",
"before": 160493.81,
"cumulativeAmount": -60345.67,
"after": 100148.14,
"type": "PERCENTAGE"
}
],
"productId": "3c2bb895-4282-41a1-8db4-2269037dc561",
"usage": 8024.690304,
"pricingTiers": [],
"subTotal": 100148.14,
"dateToSubTotalCost": {
"2021-10-06": 29951.640576,
"2021-10-07": 23967.500544,
"2021-10-08": 15939.734353999998,
"2021-10-04": 8630.129664,
"2021-10-05": 21659.129856
},
"taxCode": "SW056003",
"dateToTotalCost": {
"2021-10-06": 29951.640576,
"2021-10-07": 23967.500544,
"2021-10-08": 15939.734353999998,
"2021-10-04": 8630.129664,
"2021-10-05": 21659.129856
},
"total": 100148.14,
"unit": {
"unit": "HOUR",
"name": {}
},
"price": "20.000000",
"name": {
"en": "storage",
"fr": "storage"
},
"sku": "STORAGE",
"categoryId": "950d5a79-f6df-4770-995a-5144e6feb6b0"
},
{
"adjustments": [],
"adjustmentAggregations": [
{
"subtype": "",
"before": 11322.18,
"cumulativeAmount": -4257.14,
"after": 7065.04,
"type": "PERCENTAGE"
}
],
"productId": "6b94a874-9f85-4a14-9437-d5df30c8191d",
"usage": 377.406048,
"pricingTiers": [],
"subTotal": 7065.04,
"dateToSubTotalCost": {
"2021-10-06": 1797.12,
"2021-10-07": 1438.055424,
"2021-10-08": 956.405699,
"2021-10-04": 730.0350719999999,
"2021-10-05": 2143.4250239999997
},
"taxCode": "SW056003",
"dateToTotalCost": {
"2021-10-06": 1797.12,
"2021-10-07": 1438.055424,
"2021-10-08": 956.405699,
"2021-10-04": 730.0350719999999,
"2021-10-05": 2143.4250239999997
},
"total": 7065.04,
"unit": {
"unit": "HOUR",
"name": {}
},
"price": "30.000000",
"name": {
"en": "vm cpu",
"fr": "dancer"
},
"sku": "VM_CPU",
"categoryId": "950d5a79-f6df-4770-995a-5144e6feb6b0"
},
{
"adjustments": [
{
"itemId": "a36933e3-697a-4093-9057-18aed07479ea",
"amount": -15096.19,
"dailyDeltas": {
"2021-10-06": -3839.952,
"2021-10-07": -3072.768,
"2021-10-08": -2043.55392,
"2021-10-04": -1559.904,
"2021-10-05": -4580.016
},
"before": 30192.39,
"after": 15096.2,
"source": {
"endDate": "2021-10-15",
"subtype": "",
"scope": "PRODUCTS",
"typeString": "PERCENTAGE",
"discount": {
"discountedProducts": {
"a36933e3-697a-4093-9057-18aed07479ea": 50
},
"type": "PERCENTAGE",
"referenceId": "455feefb-0270-42ab-b9a1-ce87a430fd99",
"subtype": "",
"discountedCategories": {},
"scope": "PRODUCTS",
"name": {
"en": "vm-ram-50-percent",
"fr": "vm-ram-50-percent"
},
"id": "455feefb-0270-42ab-b9a1-ce87a430fd99",
"credit": false,
"startDate": "2021-05-08T00:00:00Z"
},
"discountId": "455feefb-0270-42ab-b9a1-ce87a430fd99",
"type": "PERCENTAGE",
"startDate": "2021-09-15",
"referenceId": "455feefb-0270-42ab-b9a1-ce87a430fd99"
},
"type": "PERCENTAGE"
}
],
"adjustmentAggregations": [
{
"scopedBefore": 30192.39,
"scopedAmount": -15096.19,
"subtype": "",
"before": 30192.39,
"cumulativeAmount": -20772.36,
"after": 9420.03,
"type": "PERCENTAGE",
"scopedAfter": 15096.2
}
],
"productId": "a36933e3-697a-4093-9057-18aed07479ea",
"usage": 754.809696,
"pricingTiers": [],
"subTotal": 9420.03,
"dateToSubTotalCost": {
"2021-10-06": 2396.1300479999995,
"2021-10-07": 1917.407231999999,
"2021-10-08": 1275.1776459999996,
"2021-10-04": 973.380096,
"2021-10-05": 2857.929984
},
"taxCode": "SW056003",
"dateToTotalCost": {
"2021-10-06": 2396.1300479999995,
"2021-10-07": 1917.407231999999,
"2021-10-08": 1275.1776459999996,
"2021-10-04": 973.380096,
"2021-10-05": 2857.929984
},
"total": 9420.03,
"unit": {
"unit": "HOUR",
"name": {}
},
"price": "40.000000",
"name": {
"en": "ram",
"fr": "ram"
},
"sku": "VM_RAM",
"categoryId": "950d5a79-f6df-4770-995a-5144e6feb6b0"
}
]
}
],
"startDate": "2021-09-15T00:00:00Z"
},
"status": "IN_PROGRESS"
}
]
}
| Optional Query Parameters | |
|---|---|
includeAllSubOrgsboolean |
Whether or not to include sub-organizations of sub-organizations or just direct sub-organizations of the reseller. |
billingCycleString |
The cycle which the invoice belongs to. Format is MM-YYYY |
| Attributes | |
|---|---|
idUUID |
The UUID of the invoice. |
invoiceIdstring |
The human readable id. |
statusenum |
The status of the invoice. Possible values are: IN_PROGRESS, IN_REVIEW, ISSUED, OVERDUE, PAID, VOID, ERROR. |
createdDatedate |
The created date of the invoice. |
draftedDatedate |
The date the invoice was marked in review. Is null if status is still IN_PROGRESS. |
issuedDatedate |
The date the invoice was issued. |
dueDatedate |
The date the invoice is due. |
organization.idUUID |
The UUID of the organization the invoice belongs to. |
organization.namestring |
The name of the organization the invoice belongs to. |
balanceBigDecimal |
The invoice's remaining balance. |
detailObject |
The invoice detail contains a currency and a list of categories. Each category has a list of products. |
detail.currencystring |
The short-name of the currency. |
detail.subTotalstring |
A string containing the total before taxes and credits. |
detail.totalstring |
The invoice total after discounts, taxes, and credits. |
detail.startDatestring |
An ISO-8601 instant format string representing the start of the invoice detail report. |
detail.endDatestring |
An ISO-8601 instant format string representing the end of the invoice detail report. |
detail.adjustmentsArray[Object] |
The adjustments applied to the invoice. An adjustment tracks the application of a discount, a credit or a tax. |
detail.adjustments.typestring |
The type of adjustment. Possible values are: PERCENTAGE, CREDIT, TAX. |
detail.adjustments.amountstring |
The adjustment amount applied to the invoice total. |
detail.adjustments.beforestring |
The invoice total before the adjustment was applied. |
detail.adjustments.afterstring |
The invoice total after the adjustment was applied. |
detail.adjustments.dailyDeltasObject |
A map of the local date to the change in daily cost due to the adjustment. |
detail.adjustments.sourceObject |
The model of the adjustment. Can be a discount or a tax model. |
detail.adjustmentAggregationsArray[Object] |
The adjustment aggregations. An aggregation summarizes the application of discounts, taxes or credits. |
detail.adjustmentAggregations.typestring |
The type of adjustment being aggregated. Possible values are: PERCENTAGE, CREDIT, TAX. |
detail.adjustmentAggregations.subtypestring |
The optional type used for sub-aggregations, like tax breakdowns. |
detail.categories.products.adjustmentAggregations.scopedAmountstring |
The adjustment amount applied to the product total. Only includes adjustments with the same scope as the item. |
detail.categories.products.adjustmentAggregations.scopedBeforestring |
The product total before the adjustments were applied. Only includes adjustments with the same scope as the item. |
detail.adjustmentAggregations.beforestring |
The invoice total before the adjustments were applied. |
detail.adjustmentAggregations.afterstring |
The invoice total after the adjustments were applied. |
detail.categories.products.adjustmentAggregations.scopedAfterstring |
The product total after the adjustments were applied. Only includes adjustments with the same scope as the item. |
detail.adjustmentAggregations.cumulativeAmountstring |
The cumulative adjustment amount applied to the invoice, its categories and their products. |
detail.categoriesArray[Object] |
An array of category objects. Contains all categories that had usage for the period. |
detail.categories.nameObject |
A map of short language codes to their translated category names. |
detail.categories.subTotalstring |
A string with the category subtotal, before taxes and credits. |
detail.categories.totalstring |
A string with the category subtotal, after taxes and credits. |
detail.adjustmentsArray[Object] |
The adjustments applied to the category. An adjustment tracks the application of a discount, a credit or a tax. |
detail.categories.adjustments.typestring |
The type of adjustment. Possible values are: PERCENTAGE, CREDIT, TAX. |
detail.categories.adjustments.itemIdUUID |
The category id. |
detail.categories.adjustments.amountstring |
The adjustment amount applied to the category total. |
detail.categories.adjustments.beforestring |
The category total before the adjustment was applied. |
detail.categories.adjustments.afterstring |
The category total after the adjustment was applied. |
detail.categories.adjustments.dailyDeltasObject |
A map of the local date to the change in daily cost due to the adjustment. |
detail.categories.adjustments.sourceObject |
The model of the adjustment. Can be a discount or a tax model. |
detail.categories.adjustmentAggregationsArray[Object] |
The adjustment aggregations. An aggregation summarizes the application of discounts, taxes or credits. |
detail.categories.adjustmentAggregations.typestring |
The type of adjustment being aggregated. Possible values are: PERCENTAGE, CREDIT, TAX. |
detail.categories.adjustmentAggregations.subtypestring |
The optional type used for sub-aggregations, like tax breakdowns. |
detail.categories.products.adjustmentAggregations.scopedAmountstring |
The adjustment amount applied to the product total. Only includes adjustments with the same scope as the item. |
detail.categories.products.adjustmentAggregations.scopedBeforestring |
The product total before the adjustments were applied. Only includes adjustments with the same scope as the item. |
detail.categories.adjustmentAggregations.beforestring |
The category total before the adjustments were applied. |
detail.categories.adjustmentAggregations.afterstring |
The category total after the adjustments were applied. |
detail.categories.products.adjustmentAggregations.scopedAfterstring |
The product total after the adjustments were applied. Only includes adjustments with the same scope as the item. |
detail.categories.adjustmentAggregations.cumulativeAmountstring |
The cumulative adjustment amount applied to the category and its products. |
detail.categories.productsObject |
A map of short language codes to their translated category names. |
detail.categories.products.skustring |
A unique string representing the sku for a product. |
detail.categories.products.nameObject |
The name object in each language for the product name. |
detail.categories.products.coststring |
A string of the summed up total cost for the product. |
detail.categories.products.usageObject |
A string of the summed up total usage for the product. |
detail.categories.products.priceObject |
A string representing the average unit price over the period. |
detail.categories.products.subTotalstring |
A string with the product subtotal, before taxes and credits. |
detail.categories.products.totalstring |
A string with the product total, after taxes and credits. |
detail.categories.products.periodstring |
The period for the product capture. Possible values: HOURS, MONTH. |
detail.categories.products.unitObject |
The unit object of the product. |
detail.categories.products.unit.unitObject |
The unit value of the product. |
detail.categories.products.unit.nameObject |
The name of the unit of the product in the required language. Only present when defining custom units. |
detail.categories.products.adjustmentsArray[Object] |
The adjustments applied to the invoice. An adjustment tracks the application of a discount, a credit or a tax. |
detail.categories.products.adjustments.typestring |
The type of adjustment. Possible values are: PERCENTAGE, CREDIT, TAX. |
detail.categories.products.adjustments.itemIdUUID |
The product id. |
detail.categories.products.adjustments.amountstring |
The adjustment amount applied to the product total. |
detail.categories.products.adjustments.beforestring |
The product total before the adjustment was applied. |
detail.categories.products.adjustments.afterstring |
The product total after the adjustment was applied. |
detail.categories.products.adjustments.dailyDeltasObject |
A map of the local date to the change in daily cost due to the adjustment. |
detail.categories.products.adjustments.sourceObject |
The model of the adjustment. Can be a discount or a tax model. |
detail.categories.products.adjustmentAggregationsArray[Object] |
The adjustment aggregations. An aggregation summarizes the application of discounts, taxes or credits. |
detail.categories.products.adjustmentAggregations.typestring |
The type of adjustment being aggregated. Possible values are: PERCENTAGE, CREDIT, TAX. |
detail.categories.products.adjustmentAggregations.subtypestring |
The optional type used for sub-aggregations, like tax breakdowns. |
detail.categories.products.adjustmentAggregations.scopedAmountstring |
The adjustment amount applied to the product total. Only includes adjustments with the same scope as the item. |
detail.categories.products.adjustmentAggregations.scopedBeforestring |
The product total before the adjustments were applied. Only includes adjustments with the same scope as the item. |
detail.categories.products.adjustmentAggregations.beforestring |
The product total before the adjustments were applied. |
detail.categories.products.adjustmentAggregations.scopedAfterstring |
The product total after the adjustments were applied. Only includes adjustments with the same scope as the item. |
detail.categories.products.adjustmentAggregations.afterstring |
The product total after the adjustments were applied. |
detail.categories.products.adjustmentAggregations.cumulativeAmountstring |
The adjustment amount applied to the product total. |
deletedAuditEventObject |
An object containing details from the deletion audit event associated to the invoice's organization. Only present if the invoice's organization is deleted. |
deletedAuditEvent.idUUID |
The ID for the audit event for the deletion of the invoice's organization. |
deletedAuditEvent.createddate |
The creation date for the deletion audit event of the invoice's organization. |
deletedAuditEvent.updateddate |
The last updated date for the deletion audit event of the invoice's organization. |
deletedAuditEvent.eventCodestring |
Will always be organizations.delete. |
deletedAuditEventCode.userIdUUID |
The ID of the user that initiated the deletion of the invoice's organization. |
deletedAuditEventCode.userEmailUUID |
The email of the user that initiated the deletion of the invoice's organization. |
List invoices of organization
GET /invoices?organization_id=:organization_id&billingCycle=MM-YYYY
Retrieve the list of invoices associated with an organization.
# Retrieve list of invoices of an organization
curl "https://cloudmc_endpoint/api/v2/invoices?organization_id=289ec5fb-0970-44e3-bca8-777a691e23c7&billingCycle=07-2021" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": [
{
"createdDate": "2021-11-22T17:22:49Z",
"billingCycle": {
"id": "7c10604c-3045-40ef-9890-1bd5a23d5a7b"
},
"organization": {
"name": "System",
"id": "c869e848-6fb3-4850-af3d-42c5666f2c78"
},
"invoiceId": "X5GDVRKGCY",
"id": "504735ce-cdc1-4adf-b59c-b4e43d1eefa4",
"detail": {
"adjustments": [
{
"amount": -41650.89,
"dailyDeltas": {
"2021-10-06": 0.0,
"2021-10-07": -1352.01792,
"2021-10-08": -899.184845,
"2021-10-02": -422.4,
"2021-10-03": -422.4,
"2021-10-04": -686.35776,
"2021-10-05": -2015.18592,
"2021-09-30": -422.4,
"2021-10-01": -422.4,
"2021-09-25": -422.4,
"2021-09-28": -422.4,
"2021-09-29": -422.4,
"2021-09-26": -422.4,
"2021-09-27": -422.4
},
"before": 189322.23,
"after": 147671.34,
"source": {
"endDate": "2021-10-15",
"subtype": "",
"scope": "ALL_PRODUCTS",
"typeString": "PERCENTAGE",
"discount": {
"discountedProducts": {},
"type": "PERCENTAGE",
"packageDiscount": 22.0,
"referenceId": "9b245d40-ba94-4e05-af51-89979d37fb29",
"subtype": "",
"discountedCategories": {},
"scope": "ALL_PRODUCTS",
"name": {
"en": "discount",
"fr": "escompte"
},
"id": "9b245d40-ba94-4e05-af51-89979d37fb29",
"credit": false,
"startDate": "2021-05-08T00:00:00Z"
},
"discountId": "9b245d40-ba94-4e05-af51-89979d37fb29",
"type": "PERCENTAGE",
"startDate": "2021-09-15",
"referenceId": "9b245d40-ba94-4e05-af51-89979d37fb29"
},
"type": "PERCENTAGE"
},
{
"amount": 0.0,
"dailyDeltas": {
"2021-09-25": 0.0
},
"before": 147671.34,
"after": 147671.34,
"source": {
"endDate": "2021-10-15",
"subtype": "",
"scope": "ALL_PRODUCTS",
"typeString": "CREDIT",
"discount": {
"discountedProducts": {},
"type": "CREDIT",
"packageDiscount": 250000.0,
"cutoffDate": "2021-09-27T00:00:00Z",
"referenceId": "532067ee-c194-4463-b5a1-a161e5c9388c",
"durationDays": 90,
"subtype": "",
"discountedCategories": {},
"scope": "ALL_PRODUCTS",
"name": {
"en": "bbbb",
"fr": "bb"
},
"id": "532067ee-c194-4463-b5a1-a161e5c9388c",
"credit": true,
"startDate": "2021-05-08T00:00:00Z"
},
"used": {
"packageDiscount": 0.0
},
"discountId": "532067ee-c194-4463-b5a1-a161e5c9388c",
"type": "CREDIT",
"startDate": "2021-09-15",
"remaining": {
"discountedProducts": {},
"discountedCategories": {},
"packageDiscount": 0.0
},
"referenceId": "532067ee-c194-4463-b5a1-a161e5c9388c"
},
"type": "CREDIT"
}
],
"adjustmentAggregations": [
{
"scopedBefore": 189322.23,
"scopedAmount": -41650.89,
"subtype": "",
"before": 251748.98,
"cumulativeAmount": -104077.64,
"after": 147671.34,
"type": "PERCENTAGE",
"scopedAfter": 147671.34
},
{
"scopedBefore": 147671.34,
"scopedAmount": 0.0,
"subtype": "",
"before": 147671.34,
"cumulativeAmount": 0.0,
"after": 147671.34,
"type": "CREDIT",
"scopedAfter": 147671.34
}
],
"endDate": "2021-10-15T00:00:00Z",
"inclusiveEndDate": "2021-10-14T00:00:00Z",
"subTotal": 147671.34,
"dateToSubTotalCost": {
"2021-10-06": 34144.890624,
"2021-10-07": 32116.48128,
"2021-10-08": 21359.336693999998,
"2021-10-02": 1497.6,
"2021-10-03": 1497.6,
"2021-10-04": 12766.995072,
"2021-10-05": 33805.234943999996,
"2021-09-30": 1497.6,
"2021-10-01": 1497.6,
"2021-09-25": 1497.6,
"2021-09-28": 1497.6,
"2021-09-29": 1497.6,
"2021-09-26": 1497.6,
"2021-09-27": 1497.6
},
"dateToTotalCost": {
"2021-10-06": 34144.890624,
"2021-10-07": 32116.48128,
"2021-10-08": 21359.336693999998,
"2021-10-02": 1497.6,
"2021-10-03": 1497.6,
"2021-10-04": 12766.995072,
"2021-10-05": 33805.234943999996,
"2021-09-30": 1497.6,
"2021-10-01": 1497.6,
"2021-09-25": 1497.6,
"2021-09-28": 1497.6,
"2021-09-29": 1497.6,
"2021-09-26": 1497.6,
"2021-09-27": 1497.6
},
"total": 147671.34,
"currency": "CAD",
"categories": [
{
"dateToTotalCost": {
"2021-10-06": 34144.890624,
"2021-10-07": 32116.48128,
"2021-10-08": 21359.336693999998,
"2021-10-02": 1497.6,
"2021-10-03": 1497.6,
"2021-10-04": 12766.995072,
"2021-10-05": 33805.234943999996,
"2021-09-30": 1497.6,
"2021-10-01": 1497.6,
"2021-09-25": 1497.6,
"2021-09-28": 1497.6,
"2021-09-29": 1497.6,
"2021-09-26": 1497.6,
"2021-09-27": 1497.6
},
"total": 147671.34,
"adjustments": [
{
"itemId": "950d5a79-f6df-4770-995a-5144e6feb6b0",
"amount": -47330.56,
"dailyDeltas": {
"2021-10-06": 0.0,
"2021-10-07": -1536.384,
"2021-10-08": -1021.80096,
"2021-10-02": -480.0,
"2021-10-03": -480.0,
"2021-10-04": -779.952,
"2021-10-05": -2289.984,
"2021-09-30": -480.0,
"2021-10-01": -480.0,
"2021-09-25": -480.0,
"2021-09-28": -480.0,
"2021-09-29": -480.0,
"2021-09-26": -480.0,
"2021-09-27": -480.0
},
"before": 236652.79,
"after": 189322.23,
"source": {
"endDate": "2021-10-15",
"subtype": "",
"scope": "CATEGORIES",
"typeString": "PERCENTAGE",
"discount": {
"discountedProducts": {},
"type": "PERCENTAGE",
"referenceId": "6ee154d1-4318-47bb-bb18-2e605c227889",
"subtype": "",
"discountedCategories": {
"950d5a79-f6df-4770-995a-5144e6feb6b0": 20
},
"scope": "CATEGORIES",
"name": {
"en": "compute-20-percent",
"fr": "compute-20-percent"
},
"id": "6ee154d1-4318-47bb-bb18-2e605c227889",
"credit": false,
"startDate": "2021-05-08T00:00:00Z"
},
"discountId": "6ee154d1-4318-47bb-bb18-2e605c227889",
"type": "PERCENTAGE",
"startDate": "2021-09-15",
"referenceId": "6ee154d1-4318-47bb-bb18-2e605c227889"
},
"type": "PERCENTAGE"
},
{
"itemId": "950d5a79-f6df-4770-995a-5144e6feb6b0",
"amount": -41650.89,
"dailyDeltas": {
"2021-10-06": 0.0,
"2021-10-07": -1352.01792,
"2021-10-08": -899.184845,
"2021-10-02": -422.4,
"2021-10-03": -422.4,
"2021-10-04": -686.35776,
"2021-10-05": -2015.18592,
"2021-09-30": -422.4,
"2021-10-01": -422.4,
"2021-09-25": -422.4,
"2021-09-28": -422.4,
"2021-09-29": -422.4,
"2021-09-26": -422.4,
"2021-09-27": -422.4
},
"before": 189322.23,
"after": 147671.34,
"source": {
"endDate": "2021-10-15",
"subtype": "",
"scope": "ALL_PRODUCTS",
"typeString": "PERCENTAGE",
"discount": {
"discountedProducts": {},
"type": "PERCENTAGE",
"packageDiscount": 22.0,
"referenceId": "9b245d40-ba94-4e05-af51-89979d37fb29",
"subtype": "",
"discountedCategories": {},
"scope": "ALL_PRODUCTS",
"name": {
"en": "discount",
"fr": "escompte"
},
"id": "9b245d40-ba94-4e05-af51-89979d37fb29",
"credit": false,
"startDate": "2021-05-08T00:00:00Z"
},
"discountId": "9b245d40-ba94-4e05-af51-89979d37fb29",
"type": "PERCENTAGE",
"startDate": "2021-09-15",
"referenceId": "9b245d40-ba94-4e05-af51-89979d37fb29"
},
"type": "PERCENTAGE"
}
],
"adjustmentAggregations": [
{
"scopedBefore": 236652.79,
"scopedAmount": -88981.45,
"subtype": "",
"before": 251748.98,
"cumulativeAmount": -104077.64,
"after": 147671.34,
"type": "PERCENTAGE",
"scopedAfter": 147671.34
}
],
"name": {
"en": "compute",
"fr": "dancer"
},
"subTotal": 147671.34,
"dateToSubTotalCost": {
"2021-10-06": 34144.890624,
"2021-10-07": 32116.48128,
"2021-10-08": 21359.336693999998,
"2021-10-02": 1497.6,
"2021-10-03": 1497.6,
"2021-10-04": 12766.995072,
"2021-10-05": 33805.234943999996,
"2021-09-30": 1497.6,
"2021-10-01": 1497.6,
"2021-09-25": 1497.6,
"2021-09-28": 1497.6,
"2021-09-29": 1497.6,
"2021-09-26": 1497.6,
"2021-09-27": 1497.6
},
"categoryId": "950d5a79-f6df-4770-995a-5144e6feb6b0",
"products": [
{
"adjustments": [],
"adjustmentAggregations": [
{
"subtype": "",
"before": 49740.6,
"cumulativeAmount": -18702.47,
"after": 31038.13,
"type": "PERCENTAGE"
}
],
"productId": "1f656184-df81-47c7-964f-eb9e27743d7b",
"usage": 497.406048,
"pricingTiers": [],
"subTotal": 31038.13,
"dateToSubTotalCost": {
"2021-10-06": 0.0,
"2021-10-07": 4793.51808,
"2021-10-08": 3188.018995,
"2021-10-02": 1497.6,
"2021-10-03": 1497.6,
"2021-10-04": 2433.450239999999,
"2021-10-05": 7144.75008,
"2021-09-30": 1497.6,
"2021-10-01": 1497.6,
"2021-09-25": 1497.6,
"2021-09-28": 1497.6,
"2021-09-29": 1497.6,
"2021-09-26": 1497.6,
"2021-09-27": 1497.6
},
"taxCode": "SW056003",
"dateToTotalCost": {
"2021-10-06": 0.0,
"2021-10-07": 4793.51808,
"2021-10-08": 3188.018995,
"2021-10-02": 1497.6,
"2021-10-03": 1497.6,
"2021-10-04": 2433.450239999999,
"2021-10-05": 7144.75008,
"2021-09-30": 1497.6,
"2021-10-01": 1497.6,
"2021-09-25": 1497.6,
"2021-09-28": 1497.6,
"2021-09-29": 1497.6,
"2021-09-26": 1497.6,
"2021-09-27": 1497.6
},
"total": 31038.13,
"unit": {
"unit": "UNIT",
"name": {}
},
"price": "100.000000",
"name": {
"en": "specification",
"fr": "specification"
},
"sku": "SPEC_PRODUCT",
"categoryId": "950d5a79-f6df-4770-995a-5144e6feb6b0"
},
{
"adjustments": [],
"adjustmentAggregations": [
{
"subtype": "",
"before": 160493.81,
"cumulativeAmount": -60345.67,
"after": 100148.14,
"type": "PERCENTAGE"
}
],
"productId": "3c2bb895-4282-41a1-8db4-2269037dc561",
"usage": 8024.690304,
"pricingTiers": [],
"subTotal": 100148.14,
"dateToSubTotalCost": {
"2021-10-06": 29951.640576,
"2021-10-07": 23967.500544,
"2021-10-08": 15939.734353999998,
"2021-10-04": 8630.129664,
"2021-10-05": 21659.129856
},
"taxCode": "SW056003",
"dateToTotalCost": {
"2021-10-06": 29951.640576,
"2021-10-07": 23967.500544,
"2021-10-08": 15939.734353999998,
"2021-10-04": 8630.129664,
"2021-10-05": 21659.129856
},
"total": 100148.14,
"unit": {
"unit": "HOUR",
"name": {}
},
"price": "20.000000",
"name": {
"en": "storage",
"fr": "storage"
},
"sku": "STORAGE",
"categoryId": "950d5a79-f6df-4770-995a-5144e6feb6b0"
},
{
"adjustments": [],
"adjustmentAggregations": [
{
"subtype": "",
"before": 11322.18,
"cumulativeAmount": -4257.14,
"after": 7065.04,
"type": "PERCENTAGE"
}
],
"productId": "6b94a874-9f85-4a14-9437-d5df30c8191d",
"usage": 377.406048,
"pricingTiers": [],
"subTotal": 7065.04,
"dateToSubTotalCost": {
"2021-10-06": 1797.12,
"2021-10-07": 1438.055424,
"2021-10-08": 956.405699,
"2021-10-04": 730.0350719999999,
"2021-10-05": 2143.4250239999997
},
"taxCode": "SW056003",
"dateToTotalCost": {
"2021-10-06": 1797.12,
"2021-10-07": 1438.055424,
"2021-10-08": 956.405699,
"2021-10-04": 730.0350719999999,
"2021-10-05": 2143.4250239999997
},
"total": 7065.04,
"unit": {
"unit": "HOUR",
"name": {}
},
"price": "30.000000",
"name": {
"en": "vm cpu",
"fr": "dancer"
},
"sku": "VM_CPU",
"categoryId": "950d5a79-f6df-4770-995a-5144e6feb6b0"
},
{
"adjustments": [
{
"itemId": "a36933e3-697a-4093-9057-18aed07479ea",
"amount": -15096.19,
"dailyDeltas": {
"2021-10-06": -3839.952,
"2021-10-07": -3072.768,
"2021-10-08": -2043.55392,
"2021-10-04": -1559.904,
"2021-10-05": -4580.016
},
"before": 30192.39,
"after": 15096.2,
"source": {
"endDate": "2021-10-15",
"subtype": "",
"scope": "PRODUCTS",
"typeString": "PERCENTAGE",
"discount": {
"discountedProducts": {
"a36933e3-697a-4093-9057-18aed07479ea": 50
},
"type": "PERCENTAGE",
"referenceId": "455feefb-0270-42ab-b9a1-ce87a430fd99",
"subtype": "",
"discountedCategories": {},
"scope": "PRODUCTS",
"name": {
"en": "vm-ram-50-percent",
"fr": "vm-ram-50-percent"
},
"id": "455feefb-0270-42ab-b9a1-ce87a430fd99",
"credit": false,
"startDate": "2021-05-08T00:00:00Z"
},
"discountId": "455feefb-0270-42ab-b9a1-ce87a430fd99",
"type": "PERCENTAGE",
"startDate": "2021-09-15",
"referenceId": "455feefb-0270-42ab-b9a1-ce87a430fd99"
},
"type": "PERCENTAGE"
}
],
"adjustmentAggregations": [
{
"scopedBefore": 30192.39,
"scopedAmount": -15096.19,
"subtype": "",
"before": 30192.39,
"cumulativeAmount": -20772.36,
"after": 9420.03,
"type": "PERCENTAGE",
"scopedAfter": 15096.2
}
],
"productId": "a36933e3-697a-4093-9057-18aed07479ea",
"usage": 754.809696,
"pricingTiers": [],
"subTotal": 9420.03,
"dateToSubTotalCost": {
"2021-10-06": 2396.1300479999995,
"2021-10-07": 1917.407231999999,
"2021-10-08": 1275.1776459999996,
"2021-10-04": 973.380096,
"2021-10-05": 2857.929984
},
"taxCode": "SW056003",
"dateToTotalCost": {
"2021-10-06": 2396.1300479999995,
"2021-10-07": 1917.407231999999,
"2021-10-08": 1275.1776459999996,
"2021-10-04": 973.380096,
"2021-10-05": 2857.929984
},
"total": 9420.03,
"unit": {
"unit": "HOUR",
"name": {}
},
"price": "40.000000",
"name": {
"en": "ram",
"fr": "ram"
},
"sku": "VM_RAM",
"categoryId": "950d5a79-f6df-4770-995a-5144e6feb6b0"
}
]
}
],
"startDate": "2021-09-15T00:00:00Z"
},
"status": "IN_PROGRESS"
}
]
}
| Optional Query Parameters | |
|---|---|
organization_idUUID |
The UUID of the organization the invoice belongs to. |
billingCycleString |
The cycle which the invoice belongs to. Format is MM-YYYY |
| Attributes | |
|---|---|
idUUID |
The UUID of the invoice. |
invoiceIdstring |
The human readable id. |
statusenum |
The status of the invoice. Possible values are: IN_PROGRESS, IN_REVIEW, ISSUED, OVERDUE, PAID, VOID, ERROR. |
createdDatedate |
The created date of the invoice. |
draftedDatedate |
The date the invoice was marked in review. Is null if status is still IN_PROGRESS. |
issuedDatedate |
The date the invoice was issued. |
dueDatedate |
The date the invoice is due. |
organization.idUUID |
The UUID of the organization the invoice belongs to. |
organization.namestring |
The name of the organization the invoice belongs to. |
balanceBigDecimal |
The invoice's remaining balance. |
detailObject |
The invoice detail contains a currency and a list of categories. Each category has a list of products. |
detail.currencystring |
The short-name of the currency. |
detail.subTotalstring |
A string containing the total before taxes and credits. |
detail.totalstring |
The invoice total after discounts, taxes, and credits. |
detail.startDatestring |
An ISO-8601 instant format string representing the start of the invoice detail report. |
detail.endDatestring |
An ISO-8601 instant format string representing the end of the invoice detail report. |
detail.adjustmentsArray[Object] |
The adjustments applied to the invoice. An adjustment tracks the application of a discount, a credit or a tax. |
detail.adjustments.typestring |
The type of adjustment. Possible values are: PERCENTAGE, CREDIT, TAX. |
detail.adjustments.amountstring |
The adjustment amount applied to the invoice total. |
detail.adjustments.beforestring |
The invoice total before the adjustment was applied. |
detail.adjustments.afterstring |
The invoice total after the adjustment was applied. |
detail.adjustments.dailyDeltasObject |
A map of the local date to the change in daily cost due to the adjustment. |
detail.adjustments.sourceObject |
The model of the adjustment. Can be a discount or a tax model. |
detail.adjustmentAggregationsArray[Object] |
The adjustment aggregations. An aggregation summarizes the application of discounts, taxes or credits. |
detail.adjustmentAggregations.typestring |
The type of adjustment being aggregated. Possible values are: PERCENTAGE, CREDIT, TAX. |
detail.adjustmentAggregations.subtypestring |
The optional type used for sub-aggregations, like tax breakdowns. |
detail.categories.products.adjustmentAggregations.scopedAmountstring |
The adjustment amount applied to the product total. Only includes adjustments with the same scope as the item. |
detail.categories.products.adjustmentAggregations.scopedBeforestring |
The product total before the adjustments were applied. Only includes adjustments with the same scope as the item. |
detail.adjustmentAggregations.beforestring |
The invoice total before the adjustments were applied. |
detail.adjustmentAggregations.afterstring |
The invoice total after the adjustments were applied. |
detail.categories.products.adjustmentAggregations.scopedAfterstring |
The product total after the adjustments were applied. Only includes adjustments with the same scope as the item. |
detail.adjustmentAggregations.cumulativeAmountstring |
The cumulative adjustment amount applied to the invoice, its categories and their products. |
detail.categoriesArray[Object] |
An array of category objects. Contains all categories that had usage for the period. |
detail.categories.nameObject |
A map of short language codes to their translated category names. |
detail.categories.subTotalstring |
A string with the category subtotal, before taxes and credits. |
detail.categories.totalstring |
A string with the category subtotal, after taxes and credits. |
detail.adjustmentsArray[Object] |
The adjustments applied to the category. An adjustment tracks the application of a discount, a credit or a tax. |
detail.categories.adjustments.typestring |
The type of adjustment. Possible values are: PERCENTAGE, CREDIT, TAX. |
detail.categories.adjustments.itemIdUUID |
The category id. |
detail.categories.adjustments.amountstring |
The adjustment amount applied to the category total. |
detail.categories.adjustments.beforestring |
The category total before the adjustment was applied. |
detail.categories.adjustments.afterstring |
The category total after the adjustment was applied. |
detail.categories.adjustments.dailyDeltasObject |
A map of the local date to the change in daily cost due to the adjustment. |
detail.categories.adjustments.sourceObject |
The model of the adjustment. Can be a discount or a tax model. |
detail.categories.adjustmentAggregationsArray[Object] |
The adjustment aggregations. An aggregation summarizes the application of discounts, taxes or credits. |
detail.categories.adjustmentAggregations.typestring |
The type of adjustment being aggregated. Possible values are: PERCENTAGE, CREDIT, TAX. |
detail.categories.adjustmentAggregations.subtypestring |
The optional type used for sub-aggregations, like tax breakdowns. |
detail.categories.products.adjustmentAggregations.scopedAmountstring |
The adjustment amount applied to the product total. Only includes adjustments with the same scope as the item. |
detail.categories.products.adjustmentAggregations.scopedBeforestring |
The product total before the adjustments were applied. Only includes adjustments with the same scope as the item. |
detail.categories.adjustmentAggregations.beforestring |
The category total before the adjustments were applied. |
detail.categories.adjustmentAggregations.afterstring |
The category total after the adjustments were applied. |
detail.categories.products.adjustmentAggregations.scopedAfterstring |
The product total after the adjustments were applied. Only includes adjustments with the same scope as the item. |
detail.categories.adjustmentAggregations.cumulativeAmountstring |
The cumulative adjustment amount applied to the category and its products. |
detail.categories.productsObject |
A map of short language codes to their translated category names. |
detail.categories.products.skustring |
A unique string representing the sku for a product. |
detail.categories.products.nameObject |
The name object in each language for the product name. |
detail.categories.products.coststring |
A string of the summed up total cost for the product. |
detail.categories.products.usageObject |
A string of the summed up total usage for the product. |
detail.categories.products.priceObject |
A string representing the average unit price over the period. |
detail.categories.products.subTotalstring |
A string with the product subtotal, before taxes and credits. |
detail.categories.products.totalstring |
A string with the product total, after taxes and credits. |
detail.categories.products.periodstring |
The period for the product capture. Possible values: HOURS, MONTH. |
detail.categories.products.unitObject |
The unit object of the product. |
detail.categories.products.unit.unitObject |
The unit value of the product. |
detail.categories.products.unit.nameObject |
The name of the unit of the product in the required language. Only present when defining custom units. |
detail.categories.products.adjustmentsArray[Object] |
The adjustments applied to the invoice. An adjustment tracks the application of a discount, a credit or a tax. |
detail.categories.products.adjustments.typestring |
The type of adjustment. Possible values are: PERCENTAGE, CREDIT, TAX. |
detail.categories.products.adjustments.itemIdUUID |
The product id. |
detail.categories.products.adjustments.amountstring |
The adjustment amount applied to the product total. |
detail.categories.products.adjustments.beforestring |
The product total before the adjustment was applied. |
detail.categories.products.adjustments.afterstring |
The product total after the adjustment was applied. |
detail.categories.products.adjustments.dailyDeltasObject |
A map of the local date to the change in daily cost due to the adjustment. |
detail.categories.products.adjustments.sourceObject |
The model of the adjustment. Can be a discount or a tax model. |
detail.categories.products.adjustmentAggregationsArray[Object] |
The adjustment aggregations. An aggregation summarizes the application of discounts, taxes or credits. |
detail.categories.products.adjustmentAggregations.typestring |
The type of adjustment being aggregated. Possible values are: PERCENTAGE, CREDIT, TAX. |
detail.categories.products.adjustmentAggregations.subtypestring |
The optional type used for sub-aggregations, like tax breakdowns. |
detail.categories.products.adjustmentAggregations.scopedAmountstring |
The adjustment amount applied to the product total. Only includes adjustments with the same scope as the item. |
detail.categories.products.adjustmentAggregations.scopedBeforestring |
The product total before the adjustments were applied. Only includes adjustments with the same scope as the item. |
detail.categories.products.adjustmentAggregations.beforestring |
The product total before the adjustments were applied. |
detail.categories.products.adjustmentAggregations.scopedAfterstring |
The product total after the adjustments were applied. Only includes adjustments with the same scope as the item. |
detail.categories.products.adjustmentAggregations.afterstring |
The product total after the adjustments were applied. |
detail.categories.products.adjustmentAggregations.cumulativeAmountstring |
The adjustment amount applied to the product total. |
List invoices of organization as a csv
GET /invoices?organization_id=:organization_id&billingCycle=MM-YYYY
Retrieve the list of invoices associated with an organization as a csv report
# Retrieve list of invoices of an organization
curl "https://cloudmc_endpoint/api/v2/invoices?organization_id=289ec5fb-0970-44e3-bca8-777a691e23c7&billingCycle=07-2021" \
-H "MC-Api-Key: your_api_key"
-H "Accept: text/csv"
The response is a list of priced products, with the first line as a header, for the given organization and billing cycle.
The format of the response is a CSV with , used as the delimiter.
organization,custom_field_1,custom_field_2,category,sku,usage,unit,currency,total_before_tax,tax_code,total_tax,tax_name1,tax_amount1,tax_name2,tax_amount2,invoice_number,status,due_date,credit_card_transaction_id,billing_start_date,billing_end_date,
AcmeCorp,null,null,Networking,BANDWIDTH,0.0043,GIGABYTE,USD,$0.00,SW056003,$0.00,QUEBEC QST/TVQ,$0.00,CANADA GST/TPS,$0.00,NFROFNGWHU,IN_REVIEW,null,null,9/20/21,10/20/21,
AcmeCorp,null,null,Compute,CCM-1M02,295.935,GIGABYTE,USD,$21.90,SW056003,$3.28,QUEBEC QST/TVQ,$2.18,CANADA GST/TPS,$1.10,NFROFNGWHU,IN_REVIEW,null,null,9/20/21,10/20/21,%
Query Parameters
| Optional | |
|---|---|
billingCycleString |
The cycle which the invoice belongs to. Format is MM-YYYY. Defaults to the latest billing cycle. |
organization_idUUID |
The reseller for which you're building the report. If not passed will default to the calling user's organization. |
languageUUID |
Language to use for the report fields (but not the headers). Expected values are "en" (English), "fr" (French) or "es" (Spanish). Defaults to "en". |
| Report Attributes | |
|---|---|
organizationString |
The organization name. |
custom_field_1String |
The organization custom field (ex: account ID). Configured in the reseller billing settings. There can be more than one custom field. |
categoryString |
The product category. |
skuString |
The SKU of the product. |
usageString |
The total usage of the product. |
unitString |
The name of the unit of the product. |
currencyString |
The short-name of the currency. |
total_before_taxString |
The total cost before taxes are applied. |
tax_codeString |
The code of the tax. |
total_taxString |
The total tax. |
tax_name1String |
The name of the tax. Depends on the tax_code, reseller billing address and customer billing address. There can be more than one tax name. |
tax_amount1String |
The amount of the tax. Depends on the tax_code, reseller billing address and customer billing address. There can be more than one tax amount. |
invoice_numberString |
The human-readable number of the invoice. |
statusString |
The status of the invoice. Possible values are: IN_PROGRESS, IN_REVIEW, ISSUED, OVERDUE, PAID, VOID, ERROR. |
due_dateString |
The date the invoice is due. |
credit_card_transaction_idString |
The confirmation number returned from the payment provider for the invoice. |
billing_start_dateString |
The billing start date of the invoice. |
billing_end_dateString |
The billing end date of the invoice. |
Approve invoice
PUT /invoices/:invoice_id/approve
Manually approve an invoice in the 'IN_REVIEW' state and issue the invoice to the customer by email. If the invoice is already in the 'ISSUED' state, an empty response will be returned and an email will not be sent. If the invoice is in any other state, an error will be thrown.
# Approve an in review invoice
curl -X PUT "https://cloudmc_endpoint/rest/invoices/20e9b8d8-b1cb-4462-b6e8-fbb8416b2cbb/approve" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": [
{
"draftedDate": "2021-11-19T17:14:44Z",
"createdDate": "2021-11-19T17:14:44Z",
"billingCycle": {
"id": "bf5d38ba-74f4-459a-be5f-2fd771cf0a68"
},
"organization": {
"customFields": {},
"name": "System",
"id": "c869e848-6fb3-4850-af3d-42c5666f2c78"
},
"invoiceId": "ZASBNWS5IH",
"id": "150006dd-697c-4021-82ab-483f5a132c2c",
"detail": {
"adjustments": [
{
"amount": -28891.86,
"dailyDeltas": {
"2021-08-11": 2111.974656,
"2021-08-10": 2111.974656,
"2021-08-13": 2111.974656,
"2021-08-12": 4223.949312,
"2021-08-04": 4223.949312,
"2021-08-14": 2111.974656,
"2021-08-06": 2111.974656,
"2021-08-05": 0.0,
"2021-08-08": 2111.974656,
"2021-08-07": 2111.974656,
"2021-08-09": 2111.974656
},
"before": 131326.62,
"after": 102434.76,
"source": {
"endDate": "2021-08-15",
"subtype": "",
"scope": "ALL_PRODUCTS",
"typeString": "PERCENTAGE",
"discount": {
"discountedProducts": {},
"type": "PERCENTAGE",
"packageDiscount": 22.0,
"referenceId": "9b245d40-ba94-4e05-af51-89979d37fb29",
"subtype": "",
"discountedCategories": {},
"scope": "ALL_PRODUCTS",
"name": {
"en": "discount",
"fr": "escompte"
},
"id": "9b245d40-ba94-4e05-af51-89979d37fb29",
"credit": false,
"startDate": "2021-05-08T00:00:00Z"
},
"discountId": "9b245d40-ba94-4e05-af51-89979d37fb29",
"type": "PERCENTAGE",
"startDate": "2021-08-04",
"referenceId": "9b245d40-ba94-4e05-af51-89979d37fb29"
},
"type": "PERCENTAGE"
},
{
"amount": -101934.76,
"dailyDeltas": {
"2021-08-11": 8536.230144,
"2021-08-10": 8536.230144,
"2021-08-13": 8536.230144,
"2021-08-12": 17072.460288,
"2021-08-04": 16572.460288,
"2021-08-14": 8536.230144,
"2021-08-06": 8536.230144,
"2021-08-05": 0.0,
"2021-08-08": 8536.230144,
"2021-08-07": 8536.230144,
"2021-08-09": 8536.230144
},
"before": 101934.76,
"after": 0.0,
"source": {
"endDate": "2021-08-15",
"subtype": "",
"scope": "ALL_PRODUCTS",
"typeString": "CREDIT",
"discount": {
"discountedProducts": {},
"type": "CREDIT",
"packageDiscount": 250000.0,
"cutoffDate": "2021-09-27T00:00:00Z",
"referenceId": "532067ee-c194-4463-b5a1-a161e5c9388c",
"durationDays": 90,
"subtype": "",
"discountedCategories": {},
"scope": "ALL_PRODUCTS",
"name": {
"en": "3 month credit",
"fr": "3 month credit fr"
},
"id": "532067ee-c194-4463-b5a1-a161e5c9388c",
"credit": true,
"startDate": "2021-05-08T00:00:00Z"
},
"used": {
"packageDiscount": -101934.76
},
"discountId": "532067ee-c194-4463-b5a1-a161e5c9388c",
"type": "CREDIT",
"startDate": "2021-08-04",
"remaining": {
"discountedProducts": {},
"discountedCategories": {},
"packageDiscount": 250000.0
},
"referenceId": "532067ee-c194-4463-b5a1-a161e5c9388c"
},
"type": "CREDIT"
}
],
"adjustmentAggregations": [
{
"scopedBefore": 131326.62,
"scopedAmount": -28891.86,
"subtype": "",
"before": 175678.27,
"cumulativeAmount": -73243.51,
"after": 102434.76,
"type": "PERCENTAGE",
"scopedAfter": 102434.76
},
{
"scopedBefore": 101934.76,
"scopedAmount": -101934.76,
"subtype": "",
"before": 102434.76,
"cumulativeAmount": -102434.76,
"after": 0.0,
"type": "CREDIT",
"scopedAfter": 0.0
}
],
"endDate": "2021-08-15T00:00:00Z",
"inclusiveEndDate": "2021-08-14T00:00:00Z",
"subTotal": 102434.76,
"dateToSubTotalCost": {
"2021-08-11": 8536.230144,
"2021-08-10": 8536.230144,
"2021-08-13": 8536.230144,
"2021-08-12": 17072.460288,
"2021-08-04": 17072.460288,
"2021-08-14": 8536.230144,
"2021-08-06": 8536.230144,
"2021-08-05": 0.0,
"2021-08-08": 8536.230144,
"2021-08-07": 8536.230144,
"2021-08-09": 8536.230144
},
"dateToTotalCost": {
"2021-08-11": 0.0,
"2021-08-10": 0.0,
"2021-08-13": 0.0,
"2021-08-12": 0.0,
"2021-08-04": 0.0,
"2021-08-14": 0.0,
"2021-08-06": 0.0,
"2021-08-05": 0.0,
"2021-08-08": 0.0,
"2021-08-07": 0.0,
"2021-08-09": 0.0
},
"total": 0.0,
"currency": "CAD",
"categories": [
{
"dateToTotalCost": {
"2021-08-11": 8536.230144,
"2021-08-10": 8536.230144,
"2021-08-13": 8536.230144,
"2021-08-12": 17072.460288,
"2021-08-04": 16572.460288,
"2021-08-14": 8536.230144,
"2021-08-06": 8536.230144,
"2021-08-05": 0.0,
"2021-08-08": 8536.230144,
"2021-08-07": 8536.230144,
"2021-08-09": 8536.230144
},
"total": 101934.76,
"adjustments": [
{
"itemId": "950d5a79-f6df-4770-995a-5144e6feb6b0",
"amount": -32831.65,
"dailyDeltas": {
"2021-08-11": 2399.9712,
"2021-08-10": 2399.9712,
"2021-08-13": 2399.9712,
"2021-08-12": 4799.9424,
"2021-08-04": 4799.9424,
"2021-08-14": 2399.9712,
"2021-08-06": 2399.9712,
"2021-08-05": 0.0,
"2021-08-08": 2399.9712,
"2021-08-07": 2399.9712,
"2021-08-09": 2399.9712
},
"before": 164158.27,
"after": 131326.62,
"source": {
"endDate": "2021-08-15",
"subtype": "",
"scope": "CATEGORIES",
"typeString": "PERCENTAGE",
"discount": {
"discountedProducts": {},
"type": "PERCENTAGE",
"referenceId": "6ee154d1-4318-47bb-bb18-2e605c227889",
"subtype": "",
"discountedCategories": {
"950d5a79-f6df-4770-995a-5144e6feb6b0": 20
},
"scope": "CATEGORIES",
"name": {
"en": "compute-20-percent",
"fr": "compute-20-percent"
},
"id": "6ee154d1-4318-47bb-bb18-2e605c227889",
"credit": false,
"startDate": "2021-05-08T00:00:00Z"
},
"discountId": "6ee154d1-4318-47bb-bb18-2e605c227889",
"type": "PERCENTAGE",
"startDate": "2021-08-04",
"referenceId": "6ee154d1-4318-47bb-bb18-2e605c227889"
},
"type": "PERCENTAGE"
},
{
"itemId": "950d5a79-f6df-4770-995a-5144e6feb6b0",
"amount": -28891.86,
"dailyDeltas": {
"2021-08-11": 2111.974656,
"2021-08-10": 2111.974656,
"2021-08-13": 2111.974656,
"2021-08-12": 4223.949312,
"2021-08-04": 4223.949312,
"2021-08-14": 2111.974656,
"2021-08-06": 2111.974656,
"2021-08-05": 0.0,
"2021-08-08": 2111.974656,
"2021-08-07": 2111.974656,
"2021-08-09": 2111.974656
},
"before": 131326.62,
"after": 102434.76,
"source": {
"endDate": "2021-08-15",
"subtype": "",
"scope": "ALL_PRODUCTS",
"typeString": "PERCENTAGE",
"discount": {
"discountedProducts": {},
"type": "PERCENTAGE",
"packageDiscount": 22.0,
"referenceId": "9b245d40-ba94-4e05-af51-89979d37fb29",
"subtype": "",
"discountedCategories": {},
"scope": "ALL_PRODUCTS",
"name": {
"en": "discount",
"fr": "escompte"
},
"id": "9b245d40-ba94-4e05-af51-89979d37fb29",
"credit": false,
"startDate": "2021-05-08T00:00:00Z"
},
"discountId": "9b245d40-ba94-4e05-af51-89979d37fb29",
"type": "PERCENTAGE",
"startDate": "2021-08-04",
"referenceId": "9b245d40-ba94-4e05-af51-89979d37fb29"
},
"type": "PERCENTAGE"
},
{
"itemId": "950d5a79-f6df-4770-995a-5144e6feb6b0",
"amount": -500.0,
"dailyDeltas": {
"2021-08-04": 500.0
},
"before": 102434.76,
"after": 101934.76,
"source": {
"endDate": "2021-08-15",
"subtype": "",
"scope": "CATEGORIES",
"typeString": "CREDIT",
"discount": {
"discountedProducts": {},
"type": "CREDIT",
"referenceId": "85d5fc06-142a-4e04-9a27-2bf08b3c1be0",
"durationDays": 600,
"subtype": "",
"discountedCategories": {
"950d5a79-f6df-4770-995a-5144e6feb6b0": 500
},
"scope": "CATEGORIES",
"name": {
"en": "compute-500-bucks",
"fr": "compute-500-bucks"
},
"id": "85d5fc06-142a-4e04-9a27-2bf08b3c1be0",
"credit": true,
"startDate": "2021-05-08T00:00:00Z"
},
"used": {
"discountedCategories": {
"950d5a79-f6df-4770-995a-5144e6feb6b0": -500.0
}
},
"discountId": "85d5fc06-142a-4e04-9a27-2bf08b3c1be0",
"type": "CREDIT",
"startDate": "2021-08-04",
"remaining": {
"discountedProducts": {},
"discountedCategories": {
"950d5a79-f6df-4770-995a-5144e6feb6b0": 500
}
},
"referenceId": "85d5fc06-142a-4e04-9a27-2bf08b3c1be0"
},
"type": "CREDIT"
}
],
"adjustmentAggregations": [
{
"scopedBefore": 164158.27,
"scopedAmount": -61723.51,
"subtype": "",
"before": 175678.27,
"cumulativeAmount": -73243.51,
"after": 102434.76,
"type": "PERCENTAGE",
"scopedAfter": 102434.76
},
{
"scopedBefore": 102434.76,
"scopedAmount": -500.0,
"subtype": "",
"before": 102434.76,
"cumulativeAmount": -500.0,
"after": 101934.76,
"type": "CREDIT",
"scopedAfter": 101934.76
}
],
"name": {
"en": "compute",
"fr": "compute"
},
"subTotal": 102434.76,
"dateToSubTotalCost": {
"2021-08-11": 8536.230144,
"2021-08-10": 8536.230144,
"2021-08-13": 8536.230144,
"2021-08-12": 17072.460288,
"2021-08-04": 17072.460288,
"2021-08-14": 8536.230144,
"2021-08-06": 8536.230144,
"2021-08-05": 0.0,
"2021-08-08": 8536.230144,
"2021-08-07": 8536.230144,
"2021-08-09": 8536.230144
},
"categoryId": "950d5a79-f6df-4770-995a-5144e6feb6b0",
"products": [
{
"adjustments": [],
"adjustmentAggregations": [
{
"subtype": "",
"before": 143998.27,
"cumulativeAmount": -54143.35,
"after": 89854.92,
"type": "PERCENTAGE"
}
],
"productId": "3c2bb895-4282-41a1-8db4-2269037dc561",
"usage": 7199.9136,
"pricingTiers": [],
"subTotal": 89854.92,
"dateToSubTotalCost": {
"2021-08-11": 7487.910144,
"2021-08-10": 7487.910144,
"2021-08-13": 7487.910144,
"2021-08-12": 14975.820288,
"2021-08-04": 14975.820288,
"2021-08-14": 7487.910144,
"2021-08-06": 7487.910144,
"2021-08-05": 0.0,
"2021-08-08": 7487.910144,
"2021-08-07": 7487.910144,
"2021-08-09": 7487.910144
},
"taxCode": "SW056003",
"dateToTotalCost": {
"2021-08-11": 7487.910144,
"2021-08-10": 7487.910144,
"2021-08-13": 7487.910144,
"2021-08-12": 14975.820288,
"2021-08-04": 14975.820288,
"2021-08-14": 7487.910144,
"2021-08-06": 7487.910144,
"2021-08-05": 0.0,
"2021-08-08": 7487.910144,
"2021-08-07": 7487.910144,
"2021-08-09": 7487.910144
},
"total": 89854.92,
"unit": {
"unit": "HOUR",
"name": {}
},
"price": "20.000000",
"name": {
"en": "storage",
"fr": "storage"
},
"sku": "STORAGE",
"categoryId": "950d5a79-f6df-4770-995a-5144e6feb6b0"
},
{
"adjustments": [],
"adjustmentAggregations": [
{
"subtype": "",
"before": 8640.0,
"cumulativeAmount": -3248.64,
"after": 5391.36,
"type": "PERCENTAGE"
}
],
"productId": "6b94a874-9f85-4a14-9437-d5df30c8191d",
"usage": 288.0,
"pricingTiers": [],
"subTotal": 5391.36,
"dateToSubTotalCost": {
"2021-08-11": 449.28,
"2021-08-10": 449.28,
"2021-08-13": 449.28,
"2021-08-12": 898.56,
"2021-08-04": 898.56,
"2021-08-14": 449.28,
"2021-08-06": 449.28,
"2021-08-05": 0.0,
"2021-08-08": 449.28,
"2021-08-07": 449.28,
"2021-08-09": 449.28
},
"taxCode": "SW056003",
"dateToTotalCost": {
"2021-08-11": 449.28,
"2021-08-10": 449.28,
"2021-08-13": 449.28,
"2021-08-12": 898.56,
"2021-08-04": 898.56,
"2021-08-14": 449.28,
"2021-08-06": 449.28,
"2021-08-05": 0.0,
"2021-08-08": 449.28,
"2021-08-07": 449.28,
"2021-08-09": 449.28
},
"total": 5391.36,
"unit": {
"unit": "HOUR",
"name": {}
},
"price": "30.000000",
"name": {
"en": "vm cpu",
"fr": "vm cpu"
},
"sku": "VM_CPU",
"categoryId": "950d5a79-f6df-4770-995a-5144e6feb6b0"
},
{
"adjustments": [
{
"itemId": "a36933e3-697a-4093-9057-18aed07479ea",
"amount": -11520.0,
"dailyDeltas": {
"2021-08-11": 960.0,
"2021-08-10": 960.0,
"2021-08-13": 960.0,
"2021-08-12": 1920.0,
"2021-08-04": 1920.0,
"2021-08-14": 960.0,
"2021-08-06": 960.0,
"2021-08-05": 0.0,
"2021-08-08": 960.0,
"2021-08-07": 960.0,
"2021-08-09": 960.0
},
"before": 23040.0,
"after": 11520.0,
"source": {
"endDate": "2021-08-15",
"subtype": "",
"scope": "PRODUCTS",
"typeString": "PERCENTAGE",
"discount": {
"discountedProducts": {
"a36933e3-697a-4093-9057-18aed07479ea": 50
},
"type": "PERCENTAGE",
"referenceId": "455feefb-0270-42ab-b9a1-ce87a430fd99",
"subtype": "",
"discountedCategories": {},
"scope": "PRODUCTS",
"name": {
"en": "vm-ram-50-percent",
"fr": "vm-ram-50-percent"
},
"id": "455feefb-0270-42ab-b9a1-ce87a430fd99",
"credit": false,
"startDate": "2021-05-08T00:00:00Z"
},
"discountId": "455feefb-0270-42ab-b9a1-ce87a430fd99",
"type": "PERCENTAGE",
"startDate": "2021-08-04",
"referenceId": "455feefb-0270-42ab-b9a1-ce87a430fd99"
},
"type": "PERCENTAGE"
}
],
"adjustmentAggregations": [
{
"scopedBefore": 23040.0,
"scopedAmount": -11520.0,
"subtype": "",
"before": 23040.0,
"cumulativeAmount": -15851.52,
"after": 7188.48,
"type": "PERCENTAGE",
"scopedAfter": 11520.0
}
],
"productId": "a36933e3-697a-4093-9057-18aed07479ea",
"usage": 576.0,
"pricingTiers": [],
"subTotal": 7188.48,
"dateToSubTotalCost": {
"2021-08-11": 599.04,
"2021-08-10": 599.04,
"2021-08-13": 599.04,
"2021-08-12": 1198.08,
"2021-08-04": 1198.08,
"2021-08-14": 599.04,
"2021-08-06": 599.04,
"2021-08-05": 0.0,
"2021-08-08": 599.04,
"2021-08-07": 599.04,
"2021-08-09": 599.04
},
"taxCode": "SW056003",
"dateToTotalCost": {
"2021-08-11": 599.04,
"2021-08-10": 599.04,
"2021-08-13": 599.04,
"2021-08-12": 1198.08,
"2021-08-04": 1198.08,
"2021-08-14": 599.04,
"2021-08-06": 599.04,
"2021-08-05": 0.0,
"2021-08-08": 599.04,
"2021-08-07": 599.04,
"2021-08-09": 599.04
},
"total": 7188.48,
"unit": {
"unit": "HOUR",
"name": {}
},
"price": "40.000000",
"name": {
"en": "ram",
"fr": "ram"
},
"sku": "VM_RAM",
"categoryId": "950d5a79-f6df-4770-995a-5144e6feb6b0"
}
]
}
],
"startDate": "2021-08-04T00:00:00Z"
},
"status": "ISSUED"
}
]
}
| Attributes | |
|---|---|
idUUID |
The UUID of the invoice. |
invoiceIdstring |
The human readable id. |
statusenum |
The status of the invoice. Possible values are: IN_PROGRESS, IN_REVIEW, ISSUED, OVERDUE, PAID, VOID, ERROR. |
createdDatedate |
The created date of the invoice. |
draftedDatedate |
The date the invoice was marked in review. Is null if status is still IN_PROGRESS. |
issuedDatedate |
The date the invoice was issued. |
dueDatedate |
The date the invoice is due. |
organization.idUUID |
The UUID of the organization the invoice belongs to. |
organization.namestring |
The name of the organization the invoice belongs to. |
balanceBigDecimal |
The invoice's remaining balance. |
detailObject |
The invoice detail contains a currency and a list of categories. Each category has a list of products. |
detail.currencystring |
The short-name of the currency. |
detail.subTotalstring |
A string containing the total before taxes and credits. |
detail.totalstring |
The invoice total after discounts, taxes, and credits. |
detail.startDatestring |
An ISO-8601 instant format string representing the start of the invoice detail report. |
detail.endDatestring |
An ISO-8601 instant format string representing the end of the invoice detail report. |
detail.adjustmentsArray[Object] |
The adjustments applied to the invoice. An adjustment tracks the application of a discount, a credit or a tax. |
detail.adjustments.typestring |
The type of adjustment. Possible values are: PERCENTAGE, CREDIT, TAX. |
detail.adjustments.amountstring |
The adjustment amount applied to the invoice total. |
detail.adjustments.beforestring |
The invoice total before the adjustment was applied. |
detail.adjustments.afterstring |
The invoice total after the adjustment was applied. |
detail.adjustments.dailyDeltasObject |
A map of the local date to the change in daily cost due to the adjustment. |
detail.adjustments.sourceObject |
The model of the adjustment. Can be a discount or a tax model. |
detail.adjustmentAggregationsArray[Object] |
The adjustment aggregations. An aggregation summarizes the application of discounts, taxes or credits. |
detail.adjustmentAggregations.typestring |
The type of adjustment being aggregated. Possible values are: PERCENTAGE, CREDIT, TAX. |
detail.adjustmentAggregations.subtypestring |
The optional type used for sub-aggregations, like tax breakdowns. |
detail.categories.products.adjustmentAggregations.scopedAmountstring |
The adjustment amount applied to the product total. Only includes adjustments with the same scope as the item. |
detail.categories.products.adjustmentAggregations.scopedBeforestring |
The product total before the adjustments were applied. Only includes adjustments with the same scope as the item. |
detail.adjustmentAggregations.beforestring |
The invoice total before the adjustments were applied. |
detail.adjustmentAggregations.afterstring |
The invoice total after the adjustments were applied. |
detail.categories.products.adjustmentAggregations.scopedAfterstring |
The product total after the adjustments were applied. Only includes adjustments with the same scope as the item. |
detail.adjustmentAggregations.cumulativeAmountstring |
The cumulative adjustment amount applied to the invoice, its categories and their products. |
detail.categoriesArray[Object] |
An array of category objects. Contains all categories that had usage for the period. |
detail.categories.nameObject |
A map of short language codes to their translated category names. |
detail.categories.subTotalstring |
A string with the category subtotal, before taxes and credits. |
detail.categories.totalstring |
A string with the category subtotal, after taxes and credits. |
detail.adjustmentsArray[Object] |
The adjustments applied to the category. An adjustment tracks the application of a discount, a credit or a tax. |
detail.categories.adjustments.typestring |
The type of adjustment. Possible values are: PERCENTAGE, CREDIT, TAX. |
detail.categories.adjustments.itemIdUUID |
The category id. |
detail.categories.adjustments.amountstring |
The adjustment amount applied to the category total. |
detail.categories.adjustments.beforestring |
The category total before the adjustment was applied. |
detail.categories.adjustments.afterstring |
The category total after the adjustment was applied. |
detail.categories.adjustments.dailyDeltasObject |
A map of the local date to the change in daily cost due to the adjustment. |
detail.categories.adjustments.sourceObject |
The model of the adjustment. Can be a discount or a tax model. |
detail.categories.adjustmentAggregationsArray[Object] |
The adjustment aggregations. An aggregation summarizes the application of discounts, taxes or credits. |
detail.categories.adjustmentAggregations.typestring |
The type of adjustment being aggregated. Possible values are: PERCENTAGE, CREDIT, TAX. |
detail.categories.adjustmentAggregations.subtypestring |
The optional type used for sub-aggregations, like tax breakdowns. |
detail.categories.products.adjustmentAggregations.scopedAmountstring |
The adjustment amount applied to the product total. Only includes adjustments with the same scope as the item. |
detail.categories.products.adjustmentAggregations.scopedBeforestring |
The product total before the adjustments were applied. Only includes adjustments with the same scope as the item. |
detail.categories.adjustmentAggregations.beforestring |
The category total before the adjustments were applied. |
detail.categories.adjustmentAggregations.afterstring |
The category total after the adjustments were applied. |
detail.categories.products.adjustmentAggregations.scopedAfterstring |
The product total after the adjustments were applied. Only includes adjustments with the same scope as the item. |
detail.categories.adjustmentAggregations.cumulativeAmountstring |
The cumulative adjustment amount applied to the category and its products. |
detail.categories.productsObject |
A map of short language codes to their translated category names. |
detail.categories.products.skustring |
A unique string representing the sku for a product. |
detail.categories.products.nameObject |
The name object in each language for the product name. |
detail.categories.products.coststring |
A string of the summed up total cost for the product. |
detail.categories.products.usageObject |
A string of the summed up total usage for the product. |
detail.categories.products.priceObject |
A string representing the average unit price over the period. |
detail.categories.products.subTotalstring |
A string with the product subtotal, before taxes and credits. |
detail.categories.products.totalstring |
A string with the product total, after taxes and credits. |
detail.categories.products.periodstring |
The period for the product capture. Possible values: HOURS, MONTH. |
detail.categories.products.unitObject |
The unit object of the product. |
detail.categories.products.unit.unitObject |
The unit value of the product. |
detail.categories.products.unit.nameObject |
The name of the unit of the product in the required language. Only present when defining custom units. |
detail.categories.products.adjustmentsArray[Object] |
The adjustments applied to the invoice. An adjustment tracks the application of a discount, a credit or a tax. |
detail.categories.products.adjustments.typestring |
The type of adjustment. Possible values are: PERCENTAGE, CREDIT, TAX. |
detail.categories.products.adjustments.itemIdUUID |
The product id. |
detail.categories.products.adjustments.amountstring |
The adjustment amount applied to the product total. |
detail.categories.products.adjustments.beforestring |
The product total before the adjustment was applied. |
detail.categories.products.adjustments.afterstring |
The product total after the adjustment was applied. |
detail.categories.products.adjustments.dailyDeltasObject |
A map of the local date to the change in daily cost due to the adjustment. |
detail.categories.products.adjustments.sourceObject |
The model of the adjustment. Can be a discount or a tax model. |
detail.categories.products.adjustmentAggregationsArray[Object] |
The adjustment aggregations. An aggregation summarizes the application of discounts, taxes or credits. |
detail.categories.products.adjustmentAggregations.typestring |
The type of adjustment being aggregated. Possible values are: PERCENTAGE, CREDIT, TAX. |
detail.categories.products.adjustmentAggregations.subtypestring |
The optional type used for sub-aggregations, like tax breakdowns. |
detail.categories.products.adjustmentAggregations.scopedAmountstring |
The adjustment amount applied to the product total. Only includes adjustments with the same scope as the item. |
detail.categories.products.adjustmentAggregations.scopedBeforestring |
The product total before the adjustments were applied. Only includes adjustments with the same scope as the item. |
detail.categories.products.adjustmentAggregations.beforestring |
The product total before the adjustments were applied. |
detail.categories.products.adjustmentAggregations.scopedAfterstring |
The product total after the adjustments were applied. Only includes adjustments with the same scope as the item. |
detail.categories.products.adjustmentAggregations.afterstring |
The product total after the adjustments were applied. |
detail.categories.products.adjustmentAggregations.cumulativeAmountstring |
The adjustment amount applied to the product total. |
Download invoice
GET /invoices/download?invoice_id=:invoice_id
Download an invoice as a PDF file.
# Download an invoice
curl -X GET 'https://cloudmc_endpoint/api/v2/invoices/download?invoice_id=3f7b7cca-d440-4c70-8ea7-ff23fe88b152' \
-H 'MC-Api-Key: your_api_key'
| Required | |
|---|---|
invoice_idUUID |
The id of the invoice. |
POST /invoices/:invoiceId/flag
Flag an invoice with a message to prevent the invoice from being automatically issued to the customer.
As with other invoices that are not in the hands of the customer, pricing configuration changes can be made to regenerate the invoice. If the configuration changes made impact the invoice, it will be voided and a new invoice will be generated. If the invoice was previously flagged, the new invoice will still have the same flag and will need to be manually approved to issue it to the customer.
# Approve a draft invoice
curl -X POST "https://cloudmc_endpoint/api/v2/invoices/20e9b8d8-b1cb-4462-b6e8-fbb8416b2cbb/flag" \
-H "MC-Api-Key: your_api_key"
| Required | |
|---|---|
invoiceIdUUID |
The id of the invoice to be flagged |
messageString |
A 280 character message about why this invoice needed to be flagged. |
Request body example:
{
"message": "The prices charged to this customer are incorrect. We should perform a pricing change and ensure the invoice is regenerated."
}
The above command return JSON structured like this:
json { "data": { "createdAt": "2022-04-08T12:40:33Z", "invoice": { "id": "0bf4b212-816b-4c6d-9466-47abeb0a0826" }, "message": "The prices charged to this customer are incorrect. We should perform a pricing change and ensure the invoice is regenerated.", "user": { "firstName": "Jason", "lastName": "Dias", "id": "f117f36e-902e-41fb-b7b2-0a6a73be5396", "email": "jdias@cloudops.com" } } }
Payments
Retreive the history of payment transactions for an organization.
List payments
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/payments?organizationId=07d88499-a17f-4a68-8888-bbec953xxx1d"
The above command returns a JSON structured like this:
{
"data": [
{
"paymentTraceReference": "925613851809199",
"paymentReference": "20210930033702-qfm04yt",
"totalAmount": 5338.72,
"confirmationNumber": "6155D9A173DE0841F48B291C2A24BE80AFB153CD",
"deleted": false,
"id": "07d88499-a17f-4a68-8560-bbec953cec1d",
"invoice": {
"createdDate": "2021-09-01T14:21:11Z",
"invoiceId": "91438A1596",
"id": "6f34d8a4-6256-4e43-96a9-6bfde2b21585"
},
"paymentDate": "2021-10-12T17:34:53Z",
"taxAmount": 253.0,
"currencyCode": "CAD",
"status": "SUCCESS",
"extraInfo": {
"approvalStatus": "1",
"procStatus": "0",
"procStatusMessage": "Approved",
"respCodeMessage": "",
"respCode": "00"
}
},
{
"paymentTraceReference": "925613851809132",
"paymentReference": "20210930033702-qfm032D",
"errorMsg": "Transport error: 412 Error: Precondition Failed",
"totalAmount": 5338.72,
"confirmationNumber": "6155D9A173DE0841F48B291C2A24BE80AFB153WE",
"id": "a8139387-b286-49e4-a458-afbaf1c604f7",
"invoice": {
"createdDate": "2021-09-01T14:21:11Z",
"invoiceId": "91438A1596",
"id": "6f34d8a4-6256-4e43-96a9-6bfde2b21585"
},
"paymentDate": "2021-10-11T17:34:50Z",
"taxAmount": 1.0,
"currencyCode": "USD",
"status": "FAIL"
}
]
}
GET /payments?organizationId=:orgId
Retrieve a list of payment processed for an organization.
| Query Params | |
|---|---|
organizationIdUUID |
The ID of the organization for which we want to see the payments. |
| Attributes | |
|---|---|
idUUID |
A payment's unique identifier. |
invoiceObject |
The invoice associated to the payment. |
invoice.idUUID |
The UUID of the invoice. |
invoice.invoiceIdString |
The human readable invoice id. |
invoice.createdDatedate |
The created date of the invoice. |
paymentReferenceString |
Payment reference sent to the payment provider to indentify the transaction. |
paymentTraceReferenceString |
Additional reference used to find a payment on the payment provider side. |
errorMsgString |
The error message returned by the payment provider if the payment failed. |
totalAmountBigDecimal |
The total amount of the invoice charged on the card. |
taxAmountBigDecimal |
The tax amount that was included in the charge. |
confirmationNumberString |
Confirmation number returned from the payment provider. |
paymentDatedate |
The date on which the payment was sent to the provider. |
currencyCodeString |
The currency of the payment. |
statusString |
Status of the payment. One of SUCCESS, PENDING, FAIL. |
extraInfoString |
Additional information set in the payment transaction. |
Retrieve a payment
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/payments/07d88499-a17f-4a68-8560-bbec953ert1d"
The above command returns a JSON structured like this:
{
"data": {
"paymentTraceReference": "925613851809199",
"paymentReference": "20210930033702-qfm04yt",
"totalAmount": 5338.72,
"confirmationNumber": "6155D9A173DE0841F48B291C2A24BE80AFB153CD",
"id": "07d88499-a17f-4a68-8560-bbec953ert1d",
"invoice": {
"createdDate": "2021-09-01T14:21:11Z",
"invoiceId": "91438A1596",
"id": "6f34d8a4-6256-4e43-96a9-6bfde2b21585"
},
"paymentDate": "2021-10-12T17:34:53Z",
"taxAmount": 253.0,
"currencyCode": "CAD",
"status": "SUCCESS",
"extraInfo": {
"approvalStatus": "1",
"procStatus": "0",
"procStatusMessage": "Approved",
"respCodeMessage": "",
"respCode": "00"
}
}
}
GET /payments/:id
Retrieve a payment.
| Attributes | |
|---|---|
idUUID |
A payment's unique identifier. |
invoiceObject |
The invoice associated to the payment. |
invoice.idUUID |
The UUID of the invoice. |
invoice.invoiceIdString |
The human readable invoice id. |
invoice.createdDatedate |
The created date of the invoice. |
paymentReferenceString |
Payment reference sent to the payment provider to indentify the transaction. |
paymentTraceReferenceString |
Additional reference used to find a payment on the payment provider side. |
errorMsgString |
The error message returned by the payment provider if the payment failed. |
totalAmountBigDecimal |
The total amount of the invoice charged on the card. |
taxAmountBigDecimal |
The tax amount that was included in the charge. |
confirmationNumberString |
Confirmation number returned from the payment provider. |
paymentDatedate |
The date on which the payment was sent to the provider. |
currencyCodeString |
The currency of the payment. |
statusString |
Status of the payment. One of SUCCESS, PENDING, FAIL. |
extraInfoString |
Additional information set in the payment transaction. |
Applied Pricing Discounts
The discount allows the assignment of a percentage discount or credit to a pricing package.
List applied pricing discounts
GET /pricing_packages/:pricing_package_id/discounts?type=:type
Retrieve the list of discounts associated with a pricing package.
# Retrieve pricing package discount list
curl "https://cloudmc_endpoint/rest/pricing_packages/efd32752-c6f2-45cf-b494-cc6be8a45845/discounts?type=PERCENTAGE" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": [
{
"discountedProducts": {},
"durationDays": 60,
"type": "PERCENTAGE",
"packageDiscount": 20.0,
"discountScope": "ALL_PRODUCTS",
"isDeactivated": true,
"discountedCategories": {},
"name": {
"en": "Summer Discount",
"fr": "Réduction Estival"
},
"id": "18db7bc6-8be1-48bb-bab1-77a7d696fa3b",
"pricingPackage": {
"id": "efd32752-c6f2-45cf-b494-cc6be8a45845"
},
"startDate": "2021-07-20T15:57:16.132Z",
"status": "CURRENT"
}
]
}
| Optional Query Parameters | |
|---|---|
typeenum |
The type of the discount. It could be either "PERCENTAGE" or "CREDIT". |
| Attributes | |
|---|---|
idUUID |
The UUID of the discount. |
discountedProductsMap[UUID, BigDecimal] |
A mapping of the desired priced product IDs and discounts. All pricing products specified will have the discount value applied to them. |
durationDaysinteger |
Duration of the discount once it has been applied to a customer. If not provided the discount will last indefinitely, or until credit values are reached. |
typeenum |
The type of the discount. It could be either "PERCENTAGE" or "CREDIT". |
packageDiscountBigDecimal |
The discount value that will be applied to all products within the pricing package. |
discountScopeenum |
The scope of the discount. It could be either "ALL_PRODUCTS", "CATEGORIES" or "PRODUCTS". |
isDeactivatedboolean |
Whether or not the discount is deactivated. Defaults to false. |
discountedCategoriesMap[UUID, BigDecimal] |
A mapping between category IDs and discount values. All pricing products within a category will have the discount value applied to them. |
nameMap[String, String] |
The name translations of the discount. |
pricingPackageObject |
The pricing package being discounted. |
pricingPackage.idUUID |
The UUID of the pricing package. |
startDatedate |
The start date of the discount. |
cutoffDatedate |
The date on which the discount will no longer be offered to customers who have not already received it. If not provided, the discount will always be offered after the start date. |
statusenum |
The status of the discount. Possible values are: UPCOMING, CURRENT, ENDED. |
Get applied pricing discount
GET /pricing_packages/:pricing_package_id/discounts/:id
Retrieve a discount's details.
# Retrieve pricing package discount list
curl "https://cloudmc_endpoint/rest/pricing_packages/efd32752-c6f2-45cf-b494-cc6be8a45845/discounts/18db7bc6-8be1-48bb-bab1-77a7d696fa3b" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": [
{
"discountedProducts": {},
"durationDays": 60,
"type": "PERCENTAGE",
"packageDiscount": 20.0,
"discountScope": "ALL_PRODUCTS",
"isDeactivated": true,
"discountedCategories": {},
"name": {
"en": "Summer Discount",
"fr": "Réduction Estival"
},
"id": "18db7bc6-8be1-48bb-bab1-77a7d696fa3b",
"pricingPackage": {
"id": "efd32752-c6f2-45cf-b494-cc6be8a45845"
},
"startDate": "2021-07-20T15:57:16.132Z",
"status": "CURRENT"
}
]
}
| Attributes | |
|---|---|
idUUID |
The UUID of the discount. |
discountedProductsMap[UUID, BigDecimal] |
A mapping of the desired priced product IDs and discounts. All pricing products specified will have the discount value applied to them. |
durationDaysinteger |
Duration of the discount once it has been applied to a customer. If not provided the discount will last indefinitely, or until credit values are reached. |
typeenum |
The type of the discount. It could be either "PERCENTAGE" or "CREDIT". |
packageDiscountBigDecimal |
The discount value that will be applied to all products within the pricing package. |
discountScopeenum |
The scope of the discount. It could be either "ALL_PRODUCTS", "CATEGORIES" or "PRODUCTS". |
isDeactivatedboolean |
Whether or not the discount is deactivated. Defaults to false. |
discountedCategoriesMap[UUID, BigDecimal] |
A mapping between category IDs and discount values. All pricing products within a category will have the discount value applied to them. |
nameMap[String, String] |
The name translations of the discount. |
pricingPackageObject |
The pricing package being discounted. |
pricingPackage.idUUID |
The UUID of the pricing package. |
startDatedate |
The start date of the discount. |
cutoffDatedate |
The date on which the discount will no longer be offered to customers who have not already received it. If not provided, the discount will always be offered after the start date. |
statusenum |
The status of the discount. Possible values are: UPCOMING, CURRENT, ENDED. |
Create applied pricing discount
POST /pricing_packages/:pricing_package_id/discounts
Create a new discount
# Creates a new pricing package discount
curl -X POST "https://cloudmc_endpoint/rest/pricing_packages/efd32752-c6f2-45cf-b494-cc6be8a45845/discounts" \
-H "MC-Api-Key: your_api_key"
Request body example:
{
"name": {
"en": "Summer Discount",
"fr": "Réduction Estival"
},
"startDate": "2021-07-23T00:00:00.000Z",
"type": "PERCENTAGE",
"durationDays": 60,
"discountedProducts": {},
"discountedCategories": {
"8cf73cc0-b86e-49b4-a102-6102894f7955": 2,
"00358632-5c9a-4164-a9a9-df271a9c06a9": 22
},
"discountScope": "CATEGORIES",
"cutoffDate": "2021-07-24T00:00:00.000Z",
}
The above command returns a JSON structured like this:
{
"data": {
"discountedProducts": {},
"durationDays": 60,
"type": "PERCENTAGE",
"discountScope": "CATEGORIES",
"discountedCategories": {
"8cf73cc0-b86e-49b4-a102-6102894f7955": 2,
"00358632-5c9a-4164-a9a9-df271a9c06a9": 22
},
"name": {
"en": "Summer Discount",
"fr": "Réduction Estival"
},
"id": "18db7bc6-8be1-48bb-bab1-77a7d696fa3b",
"pricingPackage": {
"id": "efd32752-c6f2-45cf-b494-cc6be8a45845"
},
"startDate": "2021-07-23T00:00:00.000Z",
"cutoffDate": "2021-07-24T00:00:00.000Z",
}
}
| Required | |
|---|---|
nameMap[String, String] |
The name translations of the discount. |
typeenum |
The type of the discount. It can be either "PERCENTAGE" or "CREDIT". |
startDatedate |
The start date of the discount. |
discountScopeenum |
The scope of the discount. It can be either "ALL_PRODUCTS", "CATEGORIES" or "PRODUCTS". |
packageDiscountBigDecimal |
The discount value that will be applied to all products within the pricing package. Only required if the scope is "ALL_PRODUCTS". The value must be between (0,100] for a percentage discount and greater than 0 for a credit. |
discountedCategoriesMap[UUID, BigDecimal] |
A mapping between category IDs and discount values. All pricing products within a category will have the discount value applied to them. Required to be non-empty if scope is "CATEGORIES". All discount values must be between (0,100] for a percentage discount and greater than 0 for a credit. |
discountedProductsMap[UUID, BigDecimal] |
A mapping of the desired priced product IDs and discount values. All pricing products specified will have the discount value applied to them. Required to be non-empty if scope is "PRODUCTS". All discount values must be between (0,100] for a percentage discount and greater than 0 for a credit. |
| Optional | |
|---|---|
cutoffDatedate |
The date on which the discount will no longer be offered to customers who have not already received it. If not provided, the discount will always be offered after the start date. |
durationDaysinteger |
Duration of the discount once it has been applied to a customer. If not provided the discount will last indefinitely, or until credit values are reached. |
Edit applied pricing discount
PUT /pricing_packages/:pricing_package_id/discounts/:id
Edit an existing discount that hasn't ended. Only the name and cutoff date can be edited for current discount. All fields can be edited for upcoming discounts.
# Edit an existing discount
curl -X PUT "https://cloudmc_endpoint/api/v2/pricing_packages/efd32752-c6f2-45cf-b494-cc6be8a45845/discounts/18db7bc6-8be1-48bb-bab1-77a7d696fa3b" \
-H "MC-Api-Key: your_api_key"
Request body example:
{
"name": {
"en": "End of summer Discount",
"fr": "Réduction estival fin d'été"
},
"durationDays": 60,
"discountedProducts": {},
"discountedCategories": {
"8cf73cc0-b86e-49b4-a102-6102894f7955": 2,
"00358632-5c9a-4164-a9a9-df271a9c06a9": 22
},
"discountScope": "CATEGORIES",
"cutoffDate": "2021-08-24T00:00:00.000Z",
}
The above command returns a JSON structured like this:
{
"data": {
"discountedProducts": {},
"durationDays": 60,
"type": "PERCENTAGE",
"discountScope": "CATEGORIES",
"discountedCategories": {
"8cf73cc0-b86e-49b4-a102-6102894f7955": 2,
"00358632-5c9a-4164-a9a9-df271a9c06a9": 22
},
"name": {
"en": "End of summer Discount",
"fr": "Réduction estival fin d'été"
},
"id": "18db7bc6-8be1-48bb-bab1-77a7d696fa3b",
"pricingPackage": {
"id": "efd32752-c6f2-45cf-b494-cc6be8a45845"
},
"startDate": "2021-07-23T00:00:00.000Z",
"cutoffDate": "2021-08-24T00:00:00.000Z",
"status": "UPCOMING"
}
}
| Optional | |
|---|---|
nameMap[String, String] |
The name translations of the discount. |
startDatedate |
The start date of the discount. |
discountScopeenum |
The scope of the discount. It can be either "ALL_PRODUCTS", "CATEGORIES" or "PRODUCTS". |
packageDiscountBigDecimal |
The discount value that will be applied to all products within the pricing package. Only required if the scope is "ALL_PRODUCTS". The value must be between (0,100] for a percentage discount and greater than 0 for a credit. |
discountedCategoriesMap[UUID, BigDecimal] |
A mapping between category IDs and discount values. All pricing products within a category will have the discount value applied to them. Required to be non-empty if scope is "CATEGORIES". All discount values must be between (0,100] for a percentage discount and greater than 0 for a credit. |
discountedProductsMap[UUID, BigDecimal] |
A mapping of the desired priced product IDs and discount values. All pricing products specified will have the discount value applied to them. Required to be non-empty if scope is "PRODUCTS". All discount values must be between (0,100] for a percentage discount and greater than 0 for a credit. |
cutoffDatedate |
The date on which the discount will no longer be offered to customers who have not already received it. If not provided, the discount will always be offered after the start date. |
durationDaysinteger |
Duration of the discount once it has been applied to a customer. If not provided the discount will last indefinitely, or until credit values are reached. |
Delete applied pricing discount
DELETE /pricing_packages/:pricing_package_id/discounts/:id
Delete a discount. This operation can only be performed on discounts that have status UPCOMING.
curl -X DELETE "https://cloudmc_endpoint/api/v2/pricing_packages/efd32752-c6f2-45cf-b494-cc6be8a45845/discounts/18db7bc6-8be1-48bb-bab1-77a7d696fa3b" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"taskId": "85df8dfb-b904-42dc-bb76-4824e6b50c83",
"taskStatus": "SUCCESS"
}
Deactivate applied pricing discount
PUT /pricing_packages/:pricing_package_id/discounts/:id/deactivate
Deactivate a discount. This operation can only be performed on discounts that have status CURRENT or ENDED. Deactivated is a final state, cannot be reactivated.
curl -X PUT "https://cloudmc_endpoint/api/v2/pricing_packages/efd32752-c6f2-45cf-b494-cc6be8a45845/discounts/18db7bc6-8be1-48bb-bab1-77a7d696fa3b/deactivate" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": {
"discountedProducts": {},
"durationDays": 60,
"type": "PERCENTAGE",
"discountScope": "CATEGORIES",
"isDeactivated": true,
"discountedCategories": {
"8cf73cc0-b86e-49b4-a102-6102894f7955": 2,
"00358632-5c9a-4164-a9a9-df271a9c06a9": 22
},
"name": {
"en": "End of summer Discount",
"fr": "Réduction estival fin d'été"
},
"id": "18db7bc6-8be1-48bb-bab1-77a7d696fa3b",
"pricingPackage": {
"id": "efd32752-c6f2-45cf-b494-cc6be8a45845"
},
"startDate": "2020-07-23T00:00:00.000Z",
"cutoffDate": "2020-08-24T00:00:00.000Z",
"status": "ENDED"
}
}
Organization Discounts
The discount allows the assignment of a percentage discount or credit to an organization.
List organization discounts
GET /organizations/:organization_id/discounts?type=:type
Retrieve the list of discounts associated with an organization.
# Retrieve organization discount list
curl "https://cloudmc_endpoint/api/v2/organizations/efd32752-c6f2-45cf-b494-cc6be8a45845/discounts?type=PERCENTAGE" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "1cb2b345-2b5f-4159-8466-7f3b7e092b38",
"scope": "PRODUCTS",
"status": "CURRENT",
"type": "PERCENTAGE",
"packageDiscount": null,
"discountedCategories": {},
"discountedProducts": {
"9d842142-1ce9-449f-9691-798f83925214": 10
},
"startDate": "2021-02-01T00:00:00Z",
"discountedLabels": {
"9d842142-1ce9-449f-9691-798f83925214": {
"en": "CVM-16M64"
}
},
"name": {
"en": "Custom discount CVM-16M64 products 10%",
"fr": "Custom discount CVM-16M64 products 10%"
}
},
{
"id": "93b165a7-d1eb-43cf-9bdf-9fbdd06defec",
"scope": "CATEGORIES",
"status": "CURRENT",
"type": "PERCENTAGE",
"packageDiscount": null,
"discountedCategories": {
"80140d9b-0a47-4a80-91c4-128613fc329e": 10,
"a707483d-f6a8-4a6c-8603-da856417e1e8": 10
},
"discountedProducts": {},
"startDate": "2021-02-01T00:00:00Z",
"discountedLabels": {
"80140d9b-0a47-4a80-91c4-128613fc329e": {
"en": "CDN"
},
"a707483d-f6a8-4a6c-8603-da856417e1e8": {
"en": "Storage"
}
},
"name": {
"en": "custom discount storage/CDN categories 10%",
"fr": "custom discount storage/CDN categories 10%"
}
},
{
"id": "cefa859f-07da-4113-8002-6a295e0c40e5",
"scope": "ALL_PRODUCTS",
"status": "CURRENT",
"type": "PERCENTAGE",
"packageDiscount": 10.0,
"discountedCategories": {},
"discountedProducts": {},
"startDate": "2021-02-01T00:00:00Z",
"discountedLabels": {},
"name": {
"en": "custom discount all products 10%",
"fr": "custom discount all products 10%"
}
}
]
}
| Optional Query Parameters | |
|---|---|
typeenum |
The type of the discount. It could be either "PERCENTAGE" or "CREDIT". |
| Attributes | |
|---|---|
idstring |
The id of the discount. |
nameobject[string, string] |
The name translations of the discount. |
statusenum |
The status of the discount. Possible values are: UPCOMING, CURRENT, ENDED. |
typeenum |
The type of the discount. It could be either "PERCENTAGE" or "CREDIT". |
scopeenum |
The scope of the discount. It could be either "ALL_PRODUCTS", "CATEGORIES" or "PRODUCTS". |
packageDiscountnumber |
The discount value that will be applied to all products within the applied pricing. |
discountedProductsobject[string, number] |
A mapping between product IDs and discount values. All pricing products specified will have the discount value applied to them. |
discountedCategoriesobject[string, number] |
A mapping between category IDs and discount values. All pricing products within a category will have the discount value applied to them. |
startDatedate |
The start date of the discount. |
durationDaysinteger |
Duration of the discount once it has been applied to a customer. If not provided the discount will last indefinitely, or until credit values are reached. |
Get organization discount
GET /organizations/:organization_id/discounts/:id
Retrieve a discount's details.
# Retrieve organization discount list
curl "https://cloudmc_endpoint/api/v2/organizations/efd32752-c6f2-45cf-b494-cc6be8a45845/discounts/18db7bc6-8be1-48bb-bab1-77a7d696fa3b" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": {
"discountedProducts": {},
"durationDays": 60,
"type": "PERCENTAGE",
"packageDiscount": 20.0,
"scope": "ALL_PRODUCTS",
"discountedCategories": {},
"name": {
"en": "Summer Discount",
"fr": "Réduction Estival"
},
"id": "18db7bc6-8be1-48bb-bab1-77a7d696fa3b",
"startDate": "2021-07-20T15:57:16.132Z",
"status": "CURRENT"
}
}
| Attributes | |
|---|---|
idstring |
The id of the discount. |
nameobject[string, string] |
The name translations of the discount. |
statusenum |
The status of the discount. Possible values are: UPCOMING, CURRENT, ENDED. |
typeenum |
The type of the discount. It could be either "PERCENTAGE" or "CREDIT". |
scopeenum |
The scope of the discount. It could be either "ALL_PRODUCTS", "CATEGORIES" or "PRODUCTS". |
packageDiscountnumber |
The discount value that will be applied to all products within the applied pricing. |
discountedProductsobject[string, number] |
A mapping between product IDs and discount values. All pricing products specified will have the discount value applied to them. |
discountedCategoriesobject[string, number] |
A mapping between category IDs and discount values. All pricing products within a category will have the discount value applied to them. |
startDatedate |
The start date of the discount. |
durationDaysinteger |
Duration of the discount once it has been applied to a customer. If not provided the discount will last indefinitely, or until credit values are reached. |
Create organization discount
POST /organizations/:organization_id/discounts
Create a new discount
# Creates a new discount
curl -X POST "https://cloudmc_endpoint/api/v2/organizations/efd32752-c6f2-45cf-b494-cc6be8a45845/discounts" \
-H "MC-Api-Key: your_api_key"
Request body example:
{
"name": {
"en": "Summer Discount",
"fr": "Réduction Estival"
},
"startDate": "2021-07-23T00:00:00.000Z",
"type": "PERCENTAGE",
"durationDays": 60,
"discountedProducts": {},
"discountedCategories": {
"8cf73cc0-b86e-49b4-a102-6102894f7955": 2,
"00358632-5c9a-4164-a9a9-df271a9c06a9": 22
},
"scope": "CATEGORIES",
}
The above command returns a JSON structured like this:
{
"data": {
"discountedProducts": {},
"durationDays": 60,
"type": "PERCENTAGE",
"scope": "CATEGORIES",
"discountedCategories": {
"8cf73cc0-b86e-49b4-a102-6102894f7955": 2,
"00358632-5c9a-4164-a9a9-df271a9c06a9": 22
},
"name": {
"en": "Summer Discount",
"fr": "Réduction Estival"
},
"id": "18db7bc6-8be1-48bb-bab1-77a7d696fa3b",
"startDate": "2021-07-23T00:00:00.000Z"
}
}
| Required | |
|---|---|
nameobject[string, string] |
The name translations of the discount. |
typeenum |
The type of the discount. It could be either "PERCENTAGE" or "CREDIT". |
scopeenum |
The scope of the discount. It could be either "ALL_PRODUCTS", "CATEGORIES" or "PRODUCTS". |
packageDiscountnumber |
The discount value that will be applied to all products within the applied pricing. |
discountedProductsobject[string, number] |
A mapping between product IDs and discount values. All pricing products specified will have the discount value applied to them. |
discountedCategoriesobject[string, number] |
A mapping between category IDs and discount values. All pricing products within a category will have the discount value applied to them. |
startDatedate |
The start date of the discount. Must be before the earliest ongoing billing cycle startDate. |
| Optional | |
|---|---|
durationDaysinteger |
Duration of the discount once it has been applied to a customer. If not provided the discount will last indefinitely, or until credit values are reached. |
Edit organization discount
PUT /organizations/:organization_id/discounts/:id
Edit an existing discount that hasn't ended. Only the name and cutoff date can be edited for current discount. All fields can be edited for upcoming discounts.
# Edit an existing discount
curl -X PUT "https://cloudmc_endpoint/api/v2/organizations/efd32752-c6f2-45cf-b494-cc6be8a45845/discounts/18db7bc6-8be1-48bb-bab1-77a7d696fa3b" \
-H "MC-Api-Key: your_api_key"
Request body example:
{
"discountedProducts": {
"9d842142-1ce9-449f-9691-798f83925214": 5,
"191f69c9-3a76-480e-843c-35afb9cbb1a2": 5,
"49a49de7-74c4-459f-9189-3adc7c9c1585": 5,
"b8eede50-4f5f-47ac-8a90-2b32c1a995ce": 5,
"bcd82514-d539-4d66-aaf4-b24a95ebe1cd": 5,
"47c1006d-84bf-4bb7-92c5-7bcd34baa82b": 5,
"47bb82f9-5af4-4cc3-bf79-168cc7bdb7a4": 5,
"24948849-7303-48c5-bfd8-f58f3e88a7c2": 5,
"64b8d628-89ad-41b1-8375-27c0453deef9": 5,
"9a6d318c-fa8b-437e-a8d0-cf50d933ef0c": 5,
"0642dc67-6d97-460f-9046-91fccbddc15d": 5,
"6313dba8-e971-48cb-97f9-21dc8ff4cae5": 5,
"30a3bf2c-d00a-4bff-9d24-c13af4f7f31f": 5,
"3feb88cb-b665-4481-a30f-a90746ddf25c": 5,
"757db7f8-3cef-41b2-8e08-0460dc65fc66": 5,
"414ddeb5-4df3-4ce7-ab93-2fb39c195eaf": 5
},
"type": "PERCENTAGE",
"discountedCategories": {},
"scope": "PRODUCTS",
"name": {
"en": "product discounts may 1st"
},
"startDate": "2022-05-01T00:00:00Z"
}
The above command returns a JSON structured like this:
{
"data": {
"discountedProducts": {
"9d842142-1ce9-449f-9691-798f83925214": 5,
"191f69c9-3a76-480e-843c-35afb9cbb1a2": 5,
"49a49de7-74c4-459f-9189-3adc7c9c1585": 5,
"b8eede50-4f5f-47ac-8a90-2b32c1a995ce": 5,
"bcd82514-d539-4d66-aaf4-b24a95ebe1cd": 5,
"47c1006d-84bf-4bb7-92c5-7bcd34baa82b": 5,
"47bb82f9-5af4-4cc3-bf79-168cc7bdb7a4": 5,
"24948849-7303-48c5-bfd8-f58f3e88a7c2": 5,
"64b8d628-89ad-41b1-8375-27c0453deef9": 5,
"9a6d318c-fa8b-437e-a8d0-cf50d933ef0c": 5,
"0642dc67-6d97-460f-9046-91fccbddc15d": 5,
"6313dba8-e971-48cb-97f9-21dc8ff4cae5": 5,
"30a3bf2c-d00a-4bff-9d24-c13af4f7f31f": 5,
"3feb88cb-b665-4481-a30f-a90746ddf25c": 5,
"757db7f8-3cef-41b2-8e08-0460dc65fc66": 5,
"414ddeb5-4df3-4ce7-ab93-2fb39c195eaf": 5
},
"type": "PERCENTAGE",
"mode": "ORGANIZATION",
"isDeactivated": false,
"discountedCategories": {},
"scope": "PRODUCTS",
"name": {
"en": "product discounts may 1st"
},
"id": "6f62e128-9d83-4423-9fea-9bcd5a2cfa72",
"startDate": "2022-05-01T00:00:00Z"
}
}
| Optional | |
|---|---|
nameobject[string, string] |
The name translations of the discount. |
scopeenum |
The scope of the discount. It could be either "ALL_PRODUCTS", "CATEGORIES" or "PRODUCTS". |
packageDiscountnumber |
The discount value that will be applied to all products within the applied pricing. |
discountedProductsobject[string, number] |
A mapping between product IDs and discount values. All pricing products specified will have the discount value applied to them. |
discountedCategoriesobject[string, number] |
A mapping between category IDs and discount values. All pricing products within a category will have the discount value applied to them. |
startDatedate |
The start date of the discount. |
durationDaysinteger |
Duration of the discount once it has been applied to a customer. If not provided the discount will last indefinitely, or until credit values are reached. |
Delete organization discount
DELETE /organizations/:organization_id/discounts/:id
Delete a discount. This operation can only be performed on discounts that have status UPCOMING.
curl -X DELETE "https://cloudmc_endpoint/api/v2/organizations/efd32752-c6f2-45cf-b494-cc6be8a45845/discounts/18db7bc6-8be1-48bb-bab1-77a7d696fa3b" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"taskId": "85df8dfb-b904-42dc-bb76-4824e6b50c83",
"taskStatus": "SUCCESS"
}
Authentication
Identity providers
Configure methods of authentication for your organizations.
List identity providers
GET /identity_providers
# Retrieve identity providers
curl "https://cloudmc_endpoint/api/v2/identity_providers" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": [{
"provider": "GOOGLE",
"displayName": "Google",
"logo": "aHR0cHM6Ly9kZXZlbG9wZXJzLmdvb2dsZS5jb20vaWR23nRpdHkvaW1hZ2VzL2ctbG9nby5wbmc=",
"enableSingleLogout": false,
"organization": {
"id": "5d841eb6-5913-4244-b001-917228e7aa64",
"customDomain": {
"domain": "portal.dev.cloudmc.io",
"id": "b662888e-76e5-4617-833e-304bbacfab38"
}
},
"identityProviderUsers": [
{
"user": {
"id": "0c4hc34e-ff76-48de-8976-7cb2fc89aa96"
},
"subjectId": "totallyFakeSubjectID"
}
],
"id": "02b3cbd5-9286-4cd7-b47e-22b2fb9ceae5",
"connectionName": "Google",
"type": "OIDC",
"rank": "1",
"parameters": [
{
"parameter": "issuerURL",
"id": "02b3cbd5-9286-4cd7-b47e-22b2fb9ceab1",
"value": "https://accounts.google.com"
},
{
"parameter": "clientSecret",
"id": "02b3cbd5-9286-4cd7-b47e-22b2fb9ceab3",
"value": "sssshhhhhhhhh"
},
{
"parameter": "clientID",
"id": "02b3cbd5-9286-4cd7-b47e-22b2fb9ceab4",
"value": "shhhID"
}
]
}]
}
List the identity providers configured on the system.
| Attributes | |
|---|---|
idUUID |
The id of the identity provider. |
providerstring |
The name of the provider. Possible values include the default providers (e.g GOOGLE), or CUSTOM for a custom user-defined provider. |
organizationObject |
Organization that owns this identity provider. includes: customDomain.id, customDomain.domain and name |
displayNamestring |
The display name of the identity provider that will appear on the login screen. |
logostring |
A base64 encoded data URL or URL to an image for the logo to display on the login screen. |
cssstring |
Custom css for the login button of the identity provider. |
identityProviderUsersArray |
A list of objects containing the ids of users associated with the identity provider, and their subject ids. |
connectionNamestring |
The connection name of the identity provider. |
typestring |
The type of authentication protocol. Possible values: OIDC, SAML. |
parametersArray |
A list of parameters associated with the identity provider. |
rankint |
If provided, this integer sorts identity providers on the Login page in ascending order. |
enableSingleLogoutint |
If the identity provider allows single logout. |
Create identity provider
POST /identity_providers
Create a new identity provider.
# Creates a new identity provider
curl -X POST "https://cloudmc_endpoint/api/v2/identity_providers" \
-H "MC-Api-Key: your_api_key"
Request body example:
{
"provider": "CUSTOM",
"type": "OIDC",
"connectionName": "CloudMC Google",
"displayName": "Google",
"parameters": [
{
"parameter": "issuerURL",
"value": "https://accounts.google.com"
},
{
"parameter": "clientId",
"value": "secret"
},
{
"parameter": "clientSecret",
"value": "secret"
}
]
}
The above command return JSON structured like this:
{
"data": {
"provider": "CUSTOM",
"displayName": "Google",
"connectionName": "CloudMC Google",
"type": "OIDC",
"rank": "1",
"parameters": [
{
"parameter": "issuerURL",
"id": "54d423fc-5ae2-4abc-bca6-9325376b6275",
"value": "https://accounts.google.com"
},
{
"parameter": "clientId",
"id": "a0538e7e-3049-45f0-97a5-83f55fc012e9",
"value": "secret"
},
{
"parameter": "clientSecret",
"id": "760c6c03-7c2f-4a18-a7c8-9ebc758ea33e",
"value": "secret"
}
]
}
}
| Required | |
|---|---|
idUUID |
The id of the identity provider. |
providerstring |
The name of the provider. Possible values include the default providers (e.g GOOGLE), or CUSTOM for a custom user-defined provider. |
displayNamestring |
The display name of the identity provider that will appear on the login screen. If of a default provider type, this will be set with a default if not passed. |
connectionNamestring |
The connection name of the identity provider. If of a default provider type, this will be set with a default if not passed. |
logostring |
A base64 encoded data URL or URL to an image for the logo to display on the login screen. If of a default provider type, this will be set with a default if not passed. |
typestring |
The type of authentication protocol. Possible values: OIDC, SAML. |
parametersArray |
A list of parameters associated with the identity provider. The issuerURL will be set if of a default provider type. |
rankint |
If provided, this integer sorts identity providers on the Login page in ascending order. |
| Optional | |
|---|---|
cssstring |
Custom css for the login button of the identity provider. |
Update Identity Provider
PUT /identity_providers/:id
Update an existing identity provider.
# Updates an existing identity provider
curl -X PUT "https://cloudmc_endpoint/api/v2/identity_providers/c84cfe41-929b-47c9-bde4-b55a10bd2774" \
-H "MC-Api-Key: your_api_key"
Request body example:
{
"provider": "CUSTOM",
"type": "OIDC",
"id": "c84cfe41-929b-47c9-bde4-b55a10bd2774",
"connectionName": "CloudMC Google",
"displayName": "Google",
"parameters": [
{
"parameter": "issuerURL",
"value": "https://accounts.google.com"
},
{
"parameter": "clientId",
"value": "secret"
},
{
"parameter": "clientSecret",
"value": "secret"
}
]
}
The above command return JSON structured like this:
{
"data": {
"provider": "CUSTOM",
"displayName": "Google",
"id": "da33bf85-6ba3-4214-a258-9442de149eff",
"connectionName": "CloudMC Google",
"type": "OIDC",
"rank": "1",
"parameters": [
{
"parameter": "issuerURL",
"id": "54d423fc-5ae2-4abc-bca6-9325376b6275",
"value": "https://accounts.google.com"
},
{
"parameter": "clientId",
"id": "a0538e7e-3049-45f0-97a5-83f55fc012e9",
"value": "secret"
},
{
"parameter": "clientSecret",
"id": "760c6c03-7c2f-4a18-a7c8-9ebc758ea33e",
"value": "secret"
}
]
}
}
| Required | |
|---|---|
idUUID |
The id of the identity provider. |
providerstring |
The name of the provider. Possible values include the default providers (e.g GOOGLE), or CUSTOM for a custom user-defined provider. |
displayNamestring |
The display name of the identity provider that will appear on the login screen. If of a default provider type, this will be set with a default if not passed. |
connectionNamestring |
The connection name of the identity provider. If of a default provider type, this will be set with a default if not passed. |
logostring |
A base64 encoded data URL or URL to an image for the logo to display on the login screen. If of a default provider type, this will be set with a default if not passed. |
typestring |
The type of authentication protocol. Possible values: OIDC, SAML. |
parametersArray |
A list of parameters associated with the identity provider. The issuerURL will be set if of a default provider type. |
rankint |
If provided, this integer sorts identity providers on the Login page in ascending order. |
| Optional | |
|---|---|
cssstring |
Custom css for the login button of the identity provider. |
Delete Identity Provider
Delete /identity_providers/:id
Delete an existing identity provider.
# Deletes a specified identity provider
curl -X DELETE "https://cloudmc_endpoint/api/v2/identity_providers/c84cfe41-929b-47c9-bde4-b55a10bd2774" \
-H "MC-Api-Key: your_api_key"
The above command(s) return(s) JSON structured like this:
{
"taskId": "c50390c7-9d5b-4af4-a2da-e2a2678a83e8",
"taskStatus": "SUCCESS"
}
| Attributes | |
|---|---|
taskId string |
The task id related to the identity provider deletion. |
taskStatus string |
The status of the operation. |
List default identity providers
GET /identity_providers/default_providers
# Retrieve default identity providers
curl "https://cloudmc_endpoint/api/v2/identity_providers/default_providers" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": {
"AUTH0": {
"logo": "https://cdn.auth0.com/styleguide/components/1.0.8/media/logos/img/badge.png",
"supportSingleLogout": false,
"issuerURL": "https://YOUR_AUTH0_DOMAIN",
"displayName": "Auth0"
},
"MICROSOFT": {
"logo": "https://docs.microsoft.com/en-us/azure/active-directory/develop/media/howto-add-branding-in-azure-ad-apps/ms-symbollockup_mssymbol_19.png",
"supportSingleLogout": false,
"issuerURL": "https://login.microsoftonline.com/common/v2.0",
"displayName": "Microsoft"
},
"OKTA": {
"logo": " data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA...",
"supportSingleLogout": true,
"issuerURL": "https://YOUR_OKTA_DOMAIN",
"displayName": "Okta"
},
"GOOGLE": {
"logo": "/static/img/google_signin.svg",
"prompt": "login",
"supportSingleLogout": false,
"issuerURL": "https://accounts.google.com",
"displayName": "Google"
}
}
}
List the default identity providers configured on the system.
| Attributes | |
|---|---|
dataMap |
Contains a map of all default identity providers. |
logostring |
The logo to be deisplayed. |
supportSingleLogoutint |
If the identity provider support single logout. |
issuerURLstring |
The issuer url of the identity provider. |
displayNamestring |
The display name of the identity provider that will appear on the login screen. |
Service Providers
Configure the service providers that can use CloudMC as their authentication source.
List service providers
GET /service_providers?organization_id=:organization_id
# Retrieve service providers
curl "https://cloudmc_endpoint/api/v2/service_providers?organization_id=:organization_id" \
-H "MC-Api-Key: your_api_key"
| Optional query parameters | |
|---|---|
organization_idstring |
The organization whose SAML settings are to be retrieved. If this is not provided then the request defaults to the user's organization. |
The above command returns JSON structured like this:
{
"data": [
{
"name": "Slack",
"id": "04b77783-516f-4064-a6df-e7f9cae222c1",
"type": "SAML",
"config": {
"assertionConsumerUrl": "issuer.com",
"nameIdFormat": "UNSPECIFIED",
"responseAttributes": [
{
"nameFormat": "UNSPECIFIED",
"attributeName": "username",
"attributeValueField": {
"fieldName": "firstName",
"sourceModel": "user"
}
}
],
"sign": "RESPONSE",
"serviceProviderIssuer": "slack"
},
"organization": {
"id": "976e1d4b-de6f-454b-a189-b12dd1b85112"
}
}
]
}
List the service providers of an organization
| Attributes | |
|---|---|
idUUID |
The id of the service provider. |
namestring |
The name of the service provider. |
typestring |
The type of service provider. Possible values are : SAML. |
configObject |
The object containing the configuration of the service provider. |
config.serviceProviderIssuerstring |
The issuer for the service provider. This is what is contained in the SAML request issuer tag. This is also referred to as the EntityID or EntityURL. |
config.assertionConsumerUrlstring |
The URL where the response is sent. |
config.signstring |
How the returned XML is signed. Possible values are : ASSERTION, RESPONSE, ASSERTION_AND_RESPONSE. |
config.nameIdFormatstring |
The format for the name field. Possible values are : UNSPECIFIED, EMAIL_ADDRESS, X509_SUBJECT, WINDOWS_DQN, KERBEROS_PRINCIPAL, ENTITY, PERSISTENT and TRANSIENT. |
config.responseAttributesArray[Object] |
The list of attributes part of the response |
config.responseAttributes.nameFormatstring |
The format for the name field. Possible values are : UNSPECIFIED, URI and BASIC. |
config.responseAttributes.attributeNamestring |
The attribute name |
config.responseAttributes.attributeValueFieldObject |
The object containing the source for the value in the response. |
config.responseAttributes.attributeValueField.sourceModelstring |
The model object to get the value from. Possible values are : ORGANIZATION, USER. |
config.responseAttributes.attributeValueField.fieldNamestring |
The field name to get the information from. |
organizationOrganization |
The organization tied to the service provider. |
Retrieve service provider
GET /service_providers/:id
# Retrieve service providers
curl "https://cloudmc_endpoint/api/v2/service_providers/:id" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": {
"name": "Slack",
"id": "04b77783-516f-4064-a6df-e7f9cae222c1",
"type": "SAML",
"config": {
"assertionConsumerUrl": "issuer.com",
"nameIdFormat": "UNSPECIFIED",
"responseAttributes": [
{
"nameFormat": "UNSPECIFIED",
"attributeName": "username",
"attributeValueField": {
"fieldName": "firstName",
"sourceModel": "user"
}
}
],
"sign": "RESPONSE",
"serviceProviderIssuer": "slack"
},
"organization": {
"id": "976e1d4b-de6f-454b-a189-b12dd1b85112"
}
}
}
Return the service provider configured associated to the id on the system.
| Attributes | |
|---|---|
idUUID |
The id of the service provider. |
namestring |
The name of the service provider. |
typestring |
The type of service provider. Possible values are : SAML. |
configObject |
The object containing the configuration of the service provider. |
config.serviceProviderIssuerstring |
The issuer for the service provider. This is what is contained in the SAML request issuer tag. This is also referred to as the EntityID or EntityURL. |
config.assertionConsumerUrlstring |
The URL where the response is sent. |
config.signstring |
How the returned XML is signed. Possible values are : ASSERTION, RESPONSE, ASSERTION_AND_RESPONSE. |
config.nameIdFormatstring |
The format for the name field. Possible values are : UNSPECIFIED, EMAIL_ADDRESS, X509_SUBJECT, WINDOWS_DQN, KERBEROS_PRINCIPAL, ENTITY, PERSISTENT and TRANSIENT. |
config.responseAttributesArray[Object] |
The list of attributes part of the response |
config.responseAttributes.nameFormatstring |
The format for the name field. Possible values are : UNSPECIFIED, URI and BASIC. |
config.responseAttributes.attributeNamestring |
The attribute name |
config.responseAttributes.attributeValueFieldObject |
The object containing the source for the value in the response. |
config.responseAttributes.attributeValueField.sourceModelstring |
The model object to get the value from. Possible values are : ORGANIZATION, USER. |
config.responseAttributes.attributeValueField.fieldNamestring |
The field name to get the information from. |
organizationOrganization |
The organization tied to the service provider. |
Create service provider
POST /service_providers
# Creates a new service provider
curl -X POST "https://cloudmc_endpoint/api/v2/service_providers" \
-H "MC-Api-Key: your_api_key"
Request body example:
{
"name": "Slack",
"type": "SAML",
"config": {
"assertionConsumerUrl": "https://yourdomain.slack.com/sso/saml",
"serviceProviderIssuer": "https://slack.com",
"sign": "RESPONSE",
"responseAttributes": [
{
"attributeName": "first-name",
"attributeValueField": {
"sourceModel": "user",
"fieldName": "firstName"
}
}
]
},
"organization": {
"id": "976e1d4b-de6f-454b-a189-b12dd1b85112"
}
}
The above command return JSON structured like this:
{
"data": {
"name": "Slack",
"id": "dbf3df1c-d28e-4cb5-bcb9-ce85d1675b27",
"type": "SAML",
"config": {
"assertionConsumerUrl": "https://yourdomain.slack.com/sso/saml",
"nameIdFormat": "UNSPECIFIED",
"responseAttributes": [
{
"nameFormat": "UNSPECIFIED",
"attributeName": "first-name",
"attributeValueField": {
"fieldName": "firstName",
"sourceModel": "user"
}
}
],
"name": "Slack",
"sign": "RESPONSE",
"serviceProviderIssuer": "https://slack.com"
},
"organization": {
"id": "976e1d4b-de6f-454b-a189-b12dd1b85112"
}
}
}
Create a new service provider
| Required | |
|---|---|
namestring |
The name of the service provider. |
typestring |
The type of service provider. Possible values are : SAML. |
configObject |
The object containing the configuration of the service provider. |
config.serviceProviderIssuerstring |
The issuer for the service provider. This is what is contained in the SAML request issuer tag. This is also referred to as the EntityID or EntityURL. |
config.assertionConsumerUrlstring |
The URL where the response is sent. |
config.signstring |
How the returned XML is signed. Possible values are : ASSERTION, RESPONSE, ASSERTION_AND_RESPONSE. Only required if config.responseAttributes is passed. |
config.responseAttributes.attributeNamestring |
The attribute name. Only required if config.responseAttributes is passed. |
config.responseAttributes.attributeValueFieldObject |
The object containing the source for the value in the response. Only required if config.responseAttributes is passed. |
config.responseAttributes.attributeValueField.sourceModelstring |
The model object to get the value from. Possible values are : ORGANIZATION, USER. Only required if config.responseAttributes is passed. |
config.responseAttributes.attributeValueField.fieldNamestring |
The field name to get the information from. Only required if config.responseAttributes is passed. |
organizationOrganization |
The organization tied to the service provider. |
| Optional | |
|---|---|
config.nameIdFormatstring |
The format for the name field. Possible values are : UNSPECIFIED, EMAIL_ADDRESS, X509_SUBJECT, WINDOWS_DQN, KERBEROS_PRINCIPAL, ENTITY, PERSISTENT and TRANSIENT. If not provided this defaults to UNSPECIFIED. |
config.responseAttributes.nameFormatstring |
The format for the name field. Possible values are : UNSPECIFIED, URI and BASIC. If not provided this defaults to UNSPECIFIED. |
config.responseAttributesArray[Object] |
The list of attributes part of the response. |
Update service provider
PUT /service_providers/:id
# Updates an existing service provider
curl -X PUT "https://cloudmc_endpoint/api/v2/service_providers/:id" \
-H "MC-Api-Key: your_api_key"
Request body example:
{
"name": "Slack",
"id": "dbf3df1c-d28e-4cb5-bcb9-ce85d1675b27",
"type": "SAML",
"config": {
"assertionConsumerUrl": "https://yourdomain.slack.com/sso/saml",
"serviceProviderIssuer": "https://slack.com",
"sign": "RESPONSE",
"responseAttributes": [
{
"attributeName": "first-name",
"attributeValueField": {
"sourceModel": "user",
"fieldName": "firstName"
}
}
]
},
"organization": {
"id": "976e1d4b-de6f-454b-a189-b12dd1b85112"
}
}
The above command return JSON structured like this:
{
"data": {
"name": "Slack",
"id": "dbf3df1c-d28e-4cb5-bcb9-ce85d1675b27",
"type": "SAML",
"config": {
"assertionConsumerUrl": "https://yourdomain.slack.com/sso/saml",
"nameIdFormat": "UNSPECIFIED",
"responseAttributes": [
{
"nameFormat": "UNSPECIFIED",
"attributeName": "first-name",
"attributeValueField": {
"fieldName": "firstName",
"sourceModel": "user"
}
}
],
"name": "Slack",
"sign": "RESPONSE",
"serviceProviderIssuer": "https://slack.com"
},
"organization": {
"id": "976e1d4b-de6f-454b-a189-b12dd1b85112"
}
}
}
Updates a specific service provider
| Required | |
|---|---|
namestring |
The name of the service provider. |
typestring |
The type of service provider. Possible values are : SAML. |
configObject |
The object containing the configuration of the service provider. |
config.serviceProviderIssuerstring |
The issuer for the service provider. This is what is contained in the SAML request issuer tag. This is also referred to as the EntityID or EntityURL. |
config.assertionConsumerUrlstring |
The URL where the response is sent. |
config.signstring |
How the returned XML is signed. Possible values are : ASSERTION, RESPONSE, ASSERTION_AND_RESPONSE. Only required if config.responseAttributes is passed. |
config.responseAttributes.attributeNamestring |
The attribute name. Only required if config.responseAttributes is passed. |
config.responseAttributes.attributeValueFieldObject |
The object containing the source for the value in the response. Only required if config.responseAttributes is passed. |
config.responseAttributes.attributeValueField.sourceModelstring |
The model object to get the value from. Possible values are : ORGANIZATION, USER. Only required if config.responseAttributes is passed. |
config.responseAttributes.attributeValueField.fieldNamestring |
The field name to get the information from. Only required if config.responseAttributes is passed. |
organizationOrganization |
The organization tied to the service provider. |
| Optional | |
|---|---|
config.nameIdFormatstring |
The format for the name field. Possible values are : UNSPECIFIED, EMAIL_ADDRESS, X509_SUBJECT, WINDOWS_DQN, KERBEROS_PRINCIPAL, ENTITY, PERSISTENT and TRANSIENT. If not provided this defaults to UNSPECIFIED. |
config.responseAttributes.nameFormatstring |
The format for the name field. Possible values are : UNSPECIFIED, URI and BASIC. If not provided this defaults to UNSPECIFIED. |
config.responseAttributesArray[Object] |
The list of attributes part of the response. |
Delete service provider
DELETE /service_providers/:id
# Delete a service provider
curl "https://cloudmc_endpoint/api/v2/service_providers/:id" \
-X DELETE -H "MC-Api-Key: your_api_key"
Delete a specific service provider
Get service provider metadata file
GET /service_providers/:id/metadata
# Get a service provider's metadata file
curl "https://cloudmc_endpoint/api/v2/service_providers/:id/metadata"
> The above command returns XML structured like this:
```xml
<md:EntityDescriptor entityID="https://cloudmc_endpoint">
<ds:Signature>
<ds:SignedInfo>
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
<ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
<ds:Reference URI="">
<ds:Transforms>
<ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
<ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
</ds:Transforms>
<ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
<ds:DigestValue>5U/iSjUM0ooVDT5n60sK1vgPchsZbVyp+Epm7P/GP8Y=</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>
k2k3+9IbMkUCIN/TmcZMmrG3AB6izICW10bjtnjSocz+RgnAwrUEoNQTYsOG4nsEcHFZ31zxuRJq YOnjJ259XcPGsTrZSmV/GIWxYwUcPUP292D00Ulql+Gpj5YVk31uoaWQ93fln42hbwW6Qkaaiz9i +4OXASSxx8WgBpG4Ro0Carm0fT7nJU55+ZX0bFiKRCBmbUhxXivbVj914ed2vFjkWoucG1NXvIdF L+j3Qhn3DAd/XUvR06WfPWModAl7ip/+GH97QkE7sq4szcRAKzrR10kFVLFBbMu/zZ1a0FMSc1tC vZKh1SAA61IYZy/j9OuYGCELt59f2wd+5X1+7w==
</ds:SignatureValue>
<ds:KeyInfo>
<ds:X509Data>
<ds:X509Certificate>CERT_DATA</ds:X509Data>
</ds:KeyInfo>
</ds:Signature>
<md:IDPSSODescriptor WantAuthnRequestsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect">
<md:KeyDescriptor use="signing">
<ds:KeyInfo>
<ds:X509Data>
<ds:X509Certificate>CERT_DATA</ds:X509Data>
</ds:KeyInfo>
</md:KeyDescriptor>
<md:NameIDFormat>
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
</md:NameIDFormat>
<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://cloudmc_endpoint/api/v2/service_providers/f9dea588-d7ab-4f42-b6e6-4b85f273f3db"/>
<saml2:Attribute Name="first-name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"/>
</md:IDPSSODescriptor>
</md:EntityDescriptor>
Gets the metadata file for a given service provider. This can be provided to certain identity providers for quick set-up.
SAML settings
Allows to change the configuration for the service provider integrated with SAML.
List SAML settings
GET /saml_settings?organization_id=:organization_id
# Retrieve SAML settings
curl "https://cloudmc_endpoint/api/v2/saml_settings?organization_id=:organization_id" \
-H "MC-Api-Key: your_api_key"
| Optional query parameters | |
|---|---|
organization_idstring |
The organization whose SAML settings are to be retrieved. If this is not provided then the request defaults to the user's organization. |
The above command returns JSON structured like this:
{
"data": [
{
"id": "04b77783-516f-4064-a6df-e7f9cae222c1",
"certificate": "certificate value",
"privateKey": "private key value",
"organization": {
"id": "a310f701-1d77-4bda-b3f7-8c514c5a005e"
}
}
]
}
List the SAML settings of an organization
| Attributes | |
|---|---|
idUUID |
The id of the SAML setting. |
certificatestring |
The certificate sent in the SAML response for the service provider to validate the signature. |
privateKeystring |
The private key used to sign the SAML request. |
organizationOrganization |
The organization tied to the SAML settings. |
Retrieve SAML settings
GET /saml_settings/:id
# Retrieve saml settings
curl "https://cloudmc_endpoint/api/v2/saml_settings/:id" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": {
"id": "04b77783-516f-4064-a6df-e7f9cae222c1",
"certificate": "certificate value",
"privateKey": "private key value",
"organization": {
"id": "a310f701-1d77-4bda-b3f7-8c514c5a005e"
}
}
}
Return the SAML settings of an organization
| Attributes | |
|---|---|
idUUID |
The id of the SAML setting. |
certificatestring |
The certificate sent in the SAML response for the service provider to validate the signature. |
privateKeystring |
The private key used to sign the SAML request. |
organizationOrganization |
The organization tied to the SAML settings. |
Create SAML settings
POST /saml_settings
# Updates an existing saml settings
curl -X POST "https://cloudmc_endpoint/api/v2/saml_settings/:id" \
-H "MC-Api-Key: your_api_key"
Request body example:
{
"id": "04b77783-516f-4064-a6df-e7f9cae222c1",
"certificate": "certificate value",
"privateKey": "private key value",
"organization": {
"id": "a310f701-1d77-4bda-b3f7-8c514c5a005e"
}
}
The above command return JSON structured like this:
{
"data": {
"id": "04b77783-516f-4064-a6df-e7f9cae222c1",
"certificate": "certificate value",
"privateKey": "private key value",
"organization": {
"id": "a310f701-1d77-4bda-b3f7-8c514c5a005e"
}
}
}
Creates a specific SAML settings
| Required | |
|---|---|
certificatestring |
The certificate sent in the SAML response for the service provider to validate the signature. It must use the SHA-256 algorithm. |
privateKeystring |
The private key used to sign the SAML request. It must be an RSA key of 2048 bits. |
organizationOrganization |
The organization tied to the SAML settings. |
Update SAML settings
PUT /saml_settings/:id
# Updates an existing saml settings
curl -X PUT "https://cloudmc_endpoint/api/v2/saml_settings/:id" \
-H "MC-Api-Key: your_api_key"
Request body example:
{
"id": "04b77783-516f-4064-a6df-e7f9cae222c1",
"certificate": "certificate value",
"privateKey": "private key value",
"organization": {
"id": "a310f701-1d77-4bda-b3f7-8c514c5a005e"
}
}
The above command return JSON structured like this:
{
"data": {
"id": "04b77783-516f-4064-a6df-e7f9cae222c1",
"certificate": "certificate value",
"privateKey": "private key value",
"organization": {
"id": "a310f701-1d77-4bda-b3f7-8c514c5a005e"
}
}
}
Updates a specific SAML settings
| Required | |
|---|---|
idUUID |
The id of the SAML setting. |
certificatestring |
The certificate sent in the SAML response for the service provider to validate the signature. It must use the SHA-256 algorithm. |
privateKeystring |
The private key used to sign the SAML request. It must be an RSA key of 2048 bits. |
organizationOrganization |
The organization tied to the SAML settings. |
Delete SAML settings
DELETE /saml_settings/:id
# Updates an existing saml settings
curl -X DELETE "https://cloudmc_endpoint/api/v2/saml_settings/:id" \
-H "MC-Api-Key: your_api_key"
Deletes a specific SAML settings
| Attributes | |
|---|---|
idUUID |
The id of the SAML setting |
Branding
Manage branding.
List brandings
GET /brandings
# Retrieve branding
curl "https://cloudmc_endpoint/api/v2/brandings" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": [
{
"id": "671f113c-dbbb-4478-be9c-90765b3259e5",
"factory": false,
"defaultLanguage": "en",
"organization": {
"id": "23910576-d29f-4c14-b663-31d728ff49a5"
},
"activeLanguages": "en,fr,es",
"defaultTimezone": "America/Montreal",
"applicationName": "CloudMC application",
"artifacts": [
{
"createdAt": "2020-09-14T11:42:52.000Z",
"name": "android-chrome-144x144.png",
"id": "642c73cf-d675-4b6f-826b-72d1a240542e",
"mimeType": "image/png",
"type": "FAVICON",
"content": "iVBOR...kJggg==",
"updatedAt": "2020-09-14T11:42:52.000Z"
}
]
}
]
}
List the branding configured for the organization.
| Query Params | |
|---|---|
organization_idUUID |
Return only the branding for the provided organization id. If not provided, will default to the user's organization. |
| Attributes | |
|---|---|
idUUID |
The id of the branding. |
organization.idUUID |
The organization id that the branding is linked to. |
defaultLanguagestring |
The default language. |
activeLanguagesArray[string] |
List of the possible languages. |
defaultTimezonestring |
The default timezone. |
applicationNamestring |
The application name displayed to the user. |
factoryboolean |
If the branding is the factory branding. |
artifactsArray[Object] |
The list of artifacts linked to the branding. This includes the custom css, colours css, logos, favicons. |
artifacts.idUUID |
The artifact id. |
artifacts.namestring |
The artifact name. |
artifacts.mimeTypestring |
The mime type of the artifact. |
artifacts.typestring |
The artifact type. The possibles values are: LOGO, LOGO_SQUARE, FAVICON, CUSTOM_CSS, COLORS. |
artifacts.contentstring |
The artifact content. |
artifacts.createdAtstring |
The artifact creation date. |
artifacts.updatedAtstring |
The artifact update date. |
Retrieve branding
GET /brandings/:id
# Retrieve knowledge base
curl "https://cloudmc_endpoint/api/v2/brandings/671f113c-dbbb-4478-be9c-90765b3259e5" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": {
"id": "671f113c-dbbb-4478-be9c-90765b3259e5",
"factory": false,
"defaultLanguage": "en",
"organization": {
"id": "23910576-d29f-4c14-b663-31d728ff49a5"
},
"activeLanguages": "en,fr,es",
"defaultTimezone": "America/Montreal",
"applicationName": "CloudMC application",
"artifacts": [
{
"createdAt": "2020-09-14T11:42:52.000Z",
"name": "android-chrome-144x144.png",
"id": "642c73cf-d675-4b6f-826b-72d1a240542e",
"mimeType": "image/png",
"type": "FAVICON",
"content": "iVBOR...kJggg==",
"updatedAt": "2020-09-14T11:42:52.000Z"
}
]
}
}
Retrieve the branding associated to the id.
| Attributes | |
|---|---|
idUUID |
The id of the branding. |
organization.idUUID |
The organization id that the branding is linked to. |
defaultLanguagestring |
The default language. |
activeLanguagesArray[string] |
List of the possible languages. |
defaultTimezonestring |
The default timezone. |
applicationNamestring |
The application name displayed to the user. |
factoryboolean |
If the branding is the factory branding. |
artifactsArray[Object] |
The list of artifacts linked to the branding. This includes the custom css, colours css, logos, favicons. |
artifacts.idUUID |
The artifact id. |
artifacts.namestring |
The artifact name. |
artifacts.mimeTypestring |
The mime type of the artifact. |
artifacts.typestring |
The artifact type. The possibles values are: LOGO, LOGO_SQUARE, FAVICON, CUSTOM_CSS, COLORS. |
artifacts.contentstring |
The artifact content. |
artifacts.createdAtstring |
The artifact creation date. |
artifacts.updatedAtstring |
The artifact update date. |
Knowledge Base
Manage knowledge base.
List knowledge base
GET /content/kb
# Retrieve branding
curl "https://cloudmc_endpoint/api/v2/content/kb" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": [
{
"organizationId": "23910576-d29f-4c14-b663-31d728ff49a5",
"sources": [
{
"createdDate": "2020-07-27T15:46:58Z",
"lastSyncDate": "2020-09-24T15:54:32Z",
"id": "585bd805-5b85-44af-9800-a9e55b2f619c",
"branch": "master",
"url": "https://github.com/cloudops/cloudmc-standard-kb"
}
],
"id": "1de30074-dac8-4c8b-8eda-585f9fad9c49",
"state": "READY",
"categories": [
{
"createdAt": "2020-07-27T15:46:59.000Z",
"featured": false,
"externalDocumentation": [
{
"language": "en",
"url": "http://docs.cloudstack.apache.org/en/latest/"
},
{
"language": "es",
"url": "http://docs.cloudstack.apache.org/en/latest/"
},
{
"language": "fr",
"url": "http://docs.cloudstack.apache.org/en/latest/"
}
],
"translations": [
{
"language": "en",
"id": "35b2b5e0-4944-4f92-9ddb-68eb980a31b2",
"text": "CloudStack Service",
"type": "title",
"version": 1
},
{
"language": "en",
"id": "27cb1d2d-d624-4fe7-b0d1-8677c5f3200a",
"text": "cloudstack-compute-service",
"type": "url_slug",
"version": 1
}
],
"icon": "fa fa-cloud",
"rank": 2,
"id": "47789e16-ef75-4cf8-82f7-747098533e63",
"gitKey": "cloudstack-compute-service",
"articles": [
{
"createdAt": "2020-07-27T15:47:01.000Z",
"translations": [
{
"language": "fr",
"id": "83297d87-e984-42b8-9356-2edef188b6c5",
"text": "Gestion des modèles",
"type": "title",
"version": 1
},
{
"language": "fr",
"id": "07bec89a-870e-4506-9d45-8ea977b2f9f2",
"text": "gestion-des-modeles",
"type": "url_slug",
"version": 1
},
{
"language": "fr",
"id": "aa2deeee-39a6-40f8-886b-1779c8bdbfa0",
"text": "\n\n### Créer un modèle à partir d'une instance existante...",
"type": "body",
"version": 2
}
],
"rank": 9,
"id": "05353b4b-5675-4631-b91a-6872f385c3b5",
"published": true,
"gitKey": "cloudstack-compute-service/working-with-instance-templates",
"updatedAt": "2020-09-24T15:54:36.000Z"
}
],
"updatedAt": "2020-09-24T15:54:34.000Z"
}
]
}
]
}
List the knowledge base configured for the organization.
| Query Params | |
|---|---|
organization_idUUID |
Return only the knowledge base for the provided organization id. If not provided, will default to the user's organization. |
| Attributes | |
|---|---|
idUUID |
The id of the knowledge base. |
organization.idUUID |
The organization id that the knowledge base is linked to. |
statestring |
The source state. Possible values: IMPORTING, SYNCHING, READY, ERROR. |
sourcesArray[Object] |
List of sources associated to the knowledge base |
sources.idUUID |
The source id. |
sources.urlstring |
The source URL. |
sources.branchstring |
The source branch. |
sources.createdDatestring |
The date the source was created. |
sources.lastSyncDatestring |
The last date the source was synchronized. |
categories.idUUID |
The category id. |
categories.gitKeystring |
The category git key. |
categories.rankinteger |
The category rank. |
categories.iconstring |
The category icon. |
categories.createdAtstring |
The creation date. |
categories.updatedAtstring |
The update date. |
categories.featuredboolean |
If the category needs to be displayed. |
categories.externalDocumentationArray[Object] |
List of URL and language objects. Only either 1) articles, or, 2) external documentation, will be provided for a category (example above shows both only as an example for the object structure). |
categories.externalDocumentation.languagestring |
Language of the external documentation. This indicates which URL to use based on the help center selected language. |
categories.externalDocumentation.urlstring |
URL link to the external documentation. |
categories.translationsArray[Object] |
The translation objects for the category. |
categories.translations.idUUID |
The id of the translation. |
categories.translations.languagestring |
The language of the translation. |
categories.translations.textstring |
The content of the translation. |
categories.translations.typestring |
The type of translation. Possible values are: title or url_slug. |
categories.translations.versioninteger |
The version of the translation. |
categories.articlesArray[Object] |
The list of articles in the category. |
categories.articles.idUUID |
The id of the article. |
categories.articles.publishedboolean |
If the article is published. |
categories.articles.rankinteger |
The article rank. |
categories.articles.gitKeystring |
The article git key. |
categories.articles.createdAtstring |
The creation date. |
categories.articles.updatedAtstring |
The update date. |
categories.articles.translationsArray[Object] |
The translation objects for the article. |
categories.articles.translations.idUUID |
The id of the translation. |
categories.articles.translations.languagestring |
The language of the translation. |
categories.articles.translations.textstring |
The content of the translation. |
categories.articles.translations.typestring |
The type of translation. Possible values are: title, body or url_slug. |
categories.articles.translations.versioninteger |
The version of the translation. |
Retrieve knowledge base
GET /content/kb/:id
# Retrieve trial settings
curl "https://cloudmc_endpoint/api/v2/content/kb/671f113c-dbbb-4478-be9c-90765b3259e5" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": {
"organizationId": "23910576-d29f-4c14-b663-31d728ff49a5",
"sources": [
{
"createdDate": "2020-07-27T15:46:58Z",
"lastSyncDate": "2020-09-24T15:54:32Z",
"id": "585bd805-5b85-44af-9800-a9e55b2f619c",
"branch": "master",
"url": "https://github.com/cloudops/cloudmc-standard-kb"
}
],
"id": "1de30074-dac8-4c8b-8eda-585f9fad9c49",
"state": "READY",
"categories": [
{
"createdAt": "2020-07-27T15:46:59.000Z",
"featured": false,
"externalDocumentation": [
{
"language": "en",
"url": "http://docs.cloudstack.apache.org/en/latest/"
},
{
"language": "es",
"url": "http://docs.cloudstack.apache.org/en/latest/"
},
{
"language": "fr",
"url": "http://docs.cloudstack.apache.org/en/latest/"
}
],
"translations": [
{
"language": "en",
"id": "35b2b5e0-4944-4f92-9ddb-68eb980a31b2",
"text": "CloudStack Service",
"type": "title",
"version": 1
},
{
"language": "en",
"id": "27cb1d2d-d624-4fe7-b0d1-8677c5f3200a",
"text": "cloudstack-compute-service",
"type": "url_slug",
"version": 1
}
],
"icon": "fa fa-cloud",
"rank": 2,
"id": "47789e16-ef75-4cf8-82f7-747098533e63",
"gitKey": "cloudstack-compute-service",
"articles": [
{
"createdAt": "2020-07-27T15:47:01.000Z",
"translations": [
{
"language": "fr",
"id": "83297d87-e984-42b8-9356-2edef188b6c5",
"text": "Gestion des modèles",
"type": "title",
"version": 1
},
{
"language": "fr",
"id": "07bec89a-870e-4506-9d45-8ea977b2f9f2",
"text": "gestion-des-modeles",
"type": "url_slug",
"version": 1
},
{
"language": "fr",
"id": "aa2deeee-39a6-40f8-886b-1779c8bdbfa0",
"text": "\n\n### Créer un modèle à partir d'une instance existante...",
"type": "body",
"version": 2
}
],
"rank": 9,
"id": "05353b4b-5675-4631-b91a-6872f385c3b5",
"published": true,
"gitKey": "cloudstack-compute-service/working-with-instance-templates",
"updatedAt": "2020-09-24T15:54:36.000Z"
}
],
"updatedAt": "2020-09-24T15:54:34.000Z"
}
]
}
}
Retrieve the branding associated to the id.
| Attributes | |
|---|---|
idUUID |
The id of the knowledge base. |
organization.idUUID |
The organization id that the knowledge base is linked to. |
statestring |
The source state. Possible values: IMPORTING, SYNCHING, READY, ERROR. |
sourcesArray[Object] |
List of sources associated to the knowledge base |
sources.idUUID |
The source id. |
sources.urlstring |
The source URL. |
sources.branchstring |
The source branch. |
sources.createdDatestring |
The date the source was created. |
sources.lastSyncDatestring |
The last date the source was synchronized. |
categories.idUUID |
The category id. |
categories.gitKeystring |
The category git key. |
categories.rankinteger |
The category rank. |
categories.iconstring |
The category icon. |
categories.createdAtstring |
The creation date. |
categories.updatedAtstring |
The update date. |
categories.featuredboolean |
If the category needs to be displayed. |
categories.externalDocumentationArray[Object] |
List of URL and language objects. Only either 1) articles, or, 2) external documentation, will be provided for a category (example above shows both only as an example for the object structure). |
categories.externalDocumentation.languagestring |
Language of the external documentation. This indicates which URL to use based on the help center selected language. |
categories.externalDocumentation.urlstring |
URL link to the external documentation. |
categories.translationsArray[Object] |
The translation objects for the category. |
categories.translations.idUUID |
The id of the translation. |
categories.translations.languagestring |
The language of the translation. |
categories.translations.textstring |
The content of the translation. |
categories.translations.typestring |
The type of translation. Possible values are: title or url_slug. |
categories.translations.versioninteger |
The version of the translation. |
categories.articlesArray[Object] |
The list of articles in the category. |
categories.articles.idUUID |
The id of the article. |
categories.articles.publishedboolean |
If the article is published. |
categories.articles.rankinteger |
The article rank. |
categories.articles.gitKeystring |
The article git key. |
categories.articles.createdAtstring |
The creation date. |
categories.articles.updatedAtstring |
The update date. |
categories.articles.translationsArray[Object] |
The translation objects for the article. |
categories.articles.translations.idUUID |
The id of the translation. |
categories.articles.translations.languagestring |
The language of the translation. |
categories.articles.translations.textstring |
The content of the translation. |
categories.articles.translations.typestring |
The type of translation. Possible values are: title, body or url_slug. |
categories.articles.translations.versioninteger |
The version of the translation. |
Trials
Manage trials and trials settings.
Trials Settings
Manage trials settings.
List trials settings
GET /trials_settings
# Retrieve trials settings
curl "https://cloudmc_endpoint/api/v2/trials_settings" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": [
{
"id": "b41f2aa3-e2d1-48d8-9760-8b874c20e8ae",
"organization": {
"id": "23910576-d29f-4c14-b663-31d728ff49a5",
},
"duration": 14,
"extensionDays": 7,
"maxConcurrentTrials": 5,
"cleanupDelayDays": 5,
"expirationReminderDays": 3,
"allowMultipleTrialSameEmail": false,
"enableRecaptcha": true,
"recaptchaSitekey": "6Lfg9rkZAAAAAHAwlr6_qs4QBTFRHVFgLhK3XXX",
"recaptchaSecretkey": "6Lfg9rkZAAAAAOSjYqghXeQ7zfagZTqXXXRmXXE",
"contactUsEmail": "email@gmail.com",
"contactUsPhone": "555-555-555",
"registrationHTML": {
"en": "<div>Registration HTML EN</div>",
"fr": "<div>Registration HTML FR</div>"
},
"termsAndConditionsHTML": {
"en": "<div>Terms and conditions HTML EN</div>",
"fr": "<div>Terms and conditions HTML FR</div>"
}
}
]
}
List the trials settings configured on the system.
| Query Params | |
|---|---|
organization_idUUID |
Return only settings for the provided organization id. If not provided, will default to the user organization. |
| Attributes | |
|---|---|
idUUID |
The id of the trial settings. |
organization.idUUID |
The organization id that the trial settings is linked to. |
durationinteger |
The number of days a trial account will remain active. |
extensionDaysinteger |
The number of days that a trial administrator adds when extending an active trial. |
maxConcurrentTrialsinteger |
The number of organizations that can concurrently have an active trial account. A value of zero indicates that there is no upper limit. |
cleanupDelayDaysinteger |
The number of days after the trial expiration before the system will delete the trial's resources. |
expirationReminderDaysinteger |
The number of days before the trial's end that the trial administrator will receive an email notification that the trial is about to expire. |
allowMultipleTrialSameEmailboolean |
If more than one trial account can be created using the same email address. |
enableRecaptchaboolean |
If the reCAPTCHA verification on the sign up form is displayed. The reCAPTCHA site key and secret key must be present. |
recaptchaSitekeystring |
The site key obtained from the reCAPTCHA admin console (Google). |
recaptchaSecretkeystring |
The secret key obtained from the reCAPTCHA admin console (Google). |
contactUsEmailstring |
The email address that trial user can contact for more info/support. |
contactUsPhonestring |
The phone number that trial user can contact for more info/support. |
registrationHTMLObject |
Mapped object containing the registration information HTML in different languages. |
termsAndConditionsHTMLObject |
Mapped object containing the terms and conditions HTML name in different languages. |
Retrieve trial settings
GET /trials_settings/:id
# Retrieve trial settings
curl "https://cloudmc_endpoint/api/v2/trials_settings/b41f2aa3-e2d1-48d8-9760-8b874c20e8ae" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": {
"id": "b41f2aa3-e2d1-48d8-9760-8b874c20e8ae",
"organization": {
"id": "23910576-d29f-4c14-b663-31d728ff49a5",
},
"duration": 14,
"extensionDays": 7,
"maxConcurrentTrials": 5,
"cleanupDelayDays": 5,
"expirationReminderDays": 3,
"allowMultipleTrialSameEmail": false,
"enableRecaptcha": true,
"recaptchaSitekey": "6Lfg9rkZAAAAAHAwlr6_qs4QBTFRHVFgLhK3XXX",
"recaptchaSecretkey": "6Lfg9rkZAAAAAOSjYqghXeQ7zfagZTqXXXRmXXE",
"contactUsEmail": "email@gmail.com",
"contactUsPhone": "555-555-555",
"registrationHTML": {
"en": "<div>Registration HTML EN</div>",
"fr": "<div>Registration HTML FR</div>"
},
"termsAndConditionsHTML": {
"en": "<div>Terms and conditions HTML EN</div>",
"fr": "<div>Terms and conditions HTML FR</div>"
}
}
}
Retrieve the trial settings configured associated to the id on the system.
| Attributes | |
|---|---|
idUUID |
The id of the trial settings. |
organization.idUUID |
The organization id that the trial settings is linked to. |
durationinteger |
The number of days a trial account will remain active. |
extensionDaysinteger |
The number of days that a trial administrator adds when extending an active trial. |
maxConcurrentTrialsinteger |
The number of organizations that can concurrently have an active trial account. A value of zero indicates that there is no upper limit. |
cleanupDelayDaysinteger |
The number of days after the trial expiration before the system will delete the trial's resources. |
expirationReminderDaysinteger |
The number of days before the trial's end that the trial administrator will receive an email notification that the trial is about to expire. |
allowMultipleTrialSameEmailboolean |
If more than one trial account can be created using the same email address. |
enableRecaptchaboolean |
If the reCAPTCHA verification on the sign up form is displayed. The reCAPTCHA site key and secret key must be present. |
recaptchaSitekeystring |
The site key obtained from the reCAPTCHA admin console (Google). |
recaptchaSecretkeystring |
The secret key obtained from the reCAPTCHA admin console (Google). |
contactUsEmailstring |
The email address that trial user can contact for more info/support. |
contactUsPhonestring |
The phone number that trial user can contact for more info/support. |
registrationHTMLObject |
Mapped object containing the registration information HTML in different languages. |
termsAndConditionsHTMLObject |
Mapped object containing the terms and conditions HTML name in different languages. |
Update trial settings
PUT /trials_settings/:id
# Updates an existing trial's settings
curl -X PUT "https://cloudmc_endpoint/api/v2/trials_settings/:id" \
-H "MC-Api-Key: your_api_key"
Request body example:
{
"id": "b41f2aa3-e2d1-48d8-9760-8b874c20e8ae",
"organization": {
"id": "23910576-d29f-4c14-b663-31d728ff49a5",
},
"organizationId": "23910576-d29f-4c14-b663-31d728ff49a5",
"duration": 14,
"extensionDays": 7,
"maxConcurrentTrials": 5,
"cleanupDelayDays": 5,
"expirationReminderDays": 3,
"allowMultipleTrialSameEmail": false,
"enableRecaptcha": true,
"recaptchaSitekey": "6Lfg9rkZAAAAAHAwlr6_qs4QBTFRHVFgLhK3XXX",
"recaptchaSecretkey": "6Lfg9rkZAAAAAOSjYqghXeQ7zfagZTqXXXRmXXE",
"contactUsEmail": "email@gmail.com",
"contactUsPhone": "555-555-555",
"registrationHTML": {
"en": "<div>Registration HTML EN</div>",
"fr": "<div>Registration HTML FR</div>"
},
"termsAndConditionsHTML": {
"en": "<div>Terms and conditions HTML EN</div>",
"fr": "<div>Terms and conditions HTML FR</div>"
}
}
The above command return JSON structured like this:
{
"data": {
"id": "b41f2aa3-e2d1-48d8-9760-8b874c20e8ae",
"organization": {
"id": "23910576-d29f-4c14-b663-31d728ff49a5",
},
"duration": 14,
"extensionDays": 7,
"maxConcurrentTrials": 5,
"cleanupDelayDays": 5,
"expirationReminderDays": 3,
"allowMultipleTrialSameEmail": false,
"enableRecaptcha": true,
"recaptchaSitekey": "6Lfg9rkZAAAAAHAwlr6_qs4QBTFRHVFgLhK3XXX",
"recaptchaSecretkey": "6Lfg9rkZAAAAAOSjYqghXeQ7zfagZTqXXXRmXXE",
"contactUsEmail": "email@gmail.com",
"contactUsPhone": "555-555-555",
"registrationHTML": {
"en": "<div>Registration HTML EN</div>",
"fr": "<div>Registration HTML FR</div>"
},
"termsAndConditionsHTML": {
"en": "<div>Terms and conditions HTML EN</div>",
"fr": "<div>Terms and conditions HTML FR</div>"
}
}
}
Updates a specific trial's settings.
| Required | |
|---|---|
idUUID |
The id of the trial settings. |
organization.idUUID |
The organization id that the trial settings is linked to. It cannot be changed. |
durationinteger |
The number of days a trial account will remain active. |
extensionDaysinteger |
The number of days that a trial administrator adds when extending an active trial. |
maxConcurrentTrialsinteger |
The number of organizations that can concurrently have an active trial account. A value of zero indicates that there is no upper limit. |
cleanupDelayDaysinteger |
The number of days after the trial expiration before the system will delete the trial's resources. |
expirationReminderDaysinteger |
The number of days before the trial's end that the trial administrator will receive an email notification that the trial is about to expire. |
allowMultipleTrialSameEmailboolean |
If more than one trial account can be created using the same email address. |
contactUsEmailstring |
The email address that trial user can contact for more info/support. |
registrationHTMLObject |
Mapped object containing the registration information HTML in different languages. |
termsAndConditionsHTMLObject |
Mapped object containing the terms and conditions HTML name in different languages. |
| Optional | |
|---|---|
contactUsPhonestring |
The phone number that trial user can contact for more info/support. |
enableRecaptchaboolean |
If the reCAPTCHA verification on the sign up form is displayed. The reCAPTCHA site key and secret key must be present. Default is false. |
recaptchaSitekeystring |
The site key obtained from the reCAPTCHA admin console (Google). Mandatory if recaptcha is enabled. |
recaptchaSecretkeystring |
The secret key obtained from the reCAPTCHA admin console (Google). Mandatory if recaptcha is enabled. |
Trials Management
Manage trials through it lifecycle.
List trials
GET /trials
# Retrieve trials
curl "https://cloudmc_endpoint/api/v2/trials" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": [
{
"expiryDate": "2020-10-24T13:38:57.000Z",
"hasActivatedUser": false,
"firstName": "John",
"lastName": "Doe",
"persistedOrganizationId": "0518842d-1ad6-4b66-abc4-2cf48d502b4c",
"resellerOrganization": {
"id": "23910576-d29f-4c14-b663-31d728ff49a5",
},
"createdDate": "2020-10-19T13:36:25.000Z",
"organizationName": "John Doe Corp",
"activity": [
5,
1,
0,
null,
null,
null
],
"organization": {
"serviceConnections": [
{
"commitmentTrackingEnabled": false,
"metricsTrackingEnabled": false,
"serviceCode": "gcp",
"iconOverrideUrl": "",
"name": "gcp",
"locations": [],
"id": "749e314b-d979-4882-9ba8-417862381266",
"state": "PROVISIONED",
"type": "gcp",
"reachable": true,
"trialEnvironmentLimit": 2
}
],
"name": "John Doe Corp",
"id": "0518842d-1ad6-4b66-abc4-2cf48d502b4c"
},
"id": "019d31ed-fae2-4c83-96e6-1e67c5ac5192",
"email": "john.doe@yahoo.com",
"status": "ONGOING"
}
]
}
List the trials configured on the system.
| Query Params | |
|---|---|
organization_idUUID |
Return only settings for the provided organization id. If not provided, will default to the user organization. |
| Attributes | |
|---|---|
idUUID |
The id of the trial. |
resellerOrganization.idUUID |
The reseller organization id that the trial belongs to. |
statusstring |
The status of the trial. Possible values are: SUBMITTED, PENDING, DENIED, ONGOING, EXPIRED, PURGED, CONVERTED. |
firstNamestring |
The first name of the person that requested the trial. |
lastNamestring |
The last name of the person that requested the trial. |
emailstring |
The email address of the person that requested the trial. |
organizationNamestring |
The name of the organization for which the requester is doing the trial for. |
createdDatestring |
The creation date of the trial. |
expiryDatestring |
The expiration date of the trial. |
persistedOrganizationIdUUID |
The id of the organization created in the system once the trial is approved. |
organizationObject |
The organization object created in the system for this organization once the trial is approved. |
Retrieve trial
GET /trials/:id
# Retrieve trial
curl "https://cloudmc_endpoint/api/v2/trials/b41f2aa3-e2d1-48d8-9760-8b874c20e8ae" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": {
"id": "b41f2aa3-e2d1-48d8-9760-8b874c20e8ae",
"resellerOrganization": {
"id": "23910576-d29f-4c14-b663-31d728ff49a5",
},
"lastName": "Doe",
"approvalDate": "2020-10-19T13:38:57.000Z",
"activity": [
5,
1,
0,
null,
null,
null
],
"extensionEmailDate": "2020-10-21T14:09:18.000Z",
"language": "en",
"blurb": "We need CloudMC services",
"expiryDate": "2020-10-24T13:38:57.000Z",
"email": "john.doe@yahoo.com",
"organizationName": "John Doe Corp",
"manuallyApproved": false,
"extensionCount": 0,
"hasActivatedUser": false,
"firstName": "John",
"persistedOrganizationId": "0518842d-1ad6-4b66-abc4-2cf48d502b4c",
"createdDate": "2020-10-19T13:36:25.000Z",
"phoneNumber": "5144436363",
"organization": {
"serviceConnections": [
{
"commitmentTrackingEnabled": false,
"metricsTrackingEnabled": false,
"serviceCode": "gcp",
"iconOverrideUrl": "",
"name": "gcp",
"locations": [],
"id": "749e314b-d979-4882-9ba8-417862381266",
"state": "PROVISIONED",
"type": "gcp",
"reachable": true,
"trialEnvironmentLimit": 2
}
],
"name": "John Doe Corp",
"id": "0518842d-1ad6-4b66-abc4-2cf48d502b4c"
},
"username": "john.doe@yahoo.com",
"status": "ONGOING"
}
}
Retrieve the trial associated to the id on the system.
| Attributes | |
|---|---|
idUUID |
The id of the trial. |
resellerOrganization.idUUID |
The reseller organization id that the trial belongs to. |
statusstring |
The status of the trial. Possible values are: SUBMITTED, PENDING, DENIED, ONGOING, EXPIRED, PURGED, CONVERTED. |
firstNamestring |
The first name of the person that requested the trial. |
lastNamestring |
The last name of the person that requested the trial. |
emailstring |
The email address of the person that requested the trial. |
phoneNumberstring |
The phone number of the person that requested the trial. |
organizationNamestring |
The name of the organization for which the requester is doing the trial for. |
createdDatestring |
The creation date of the trial. |
expiryDatestring |
The expiration date of the trial. |
persistedOrganizationIdUUID |
The id of the organization created in the system once the trial is approved. |
organizationObject |
The organization object created in the system for this organization once the trial is approved. |
usernamestring |
The username associated to the creator of the trial. |
approvalDatestring |
The approval date of the trial. |
denialDatestring |
The denial date of the trial. |
denialReasonstring |
The reason the trial is denied. |
extensionCountinteger |
The number of times the trial was extended. |
languagestring |
The language used when creating the trial. |
manuallyApprovedboolean |
If the trial is manually approved. |
extensionEmailDatestring |
The date the extension email notification was sent. |
extensionDatestring |
The date the trial was extended. |
shutdownDatestring |
The date the trial was shutdown. |
purgeDatestring |
The date the trial was purged. |
conversionDatestring |
The date the trial was converted to an active organization. |
blurbstring |
The cloud requirements entered in the trial registration. |
Trial remaining slots
POST /trials/:id/remaining
# Get trial remaining slots
curl -X GET "https://cloudmc_endpoint/api/v2/trials/remaining" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": 10
}
Indicates how many organizations can concurrently have an active trial with automatic approval.
| Query Params | |
|---|---|
organization_idUUID |
Return only settings for the provided organization id. If not provided, it will default to the reseller configuration matching the url. |
Activate trial
POST /trials/:id/activate
# Activate a trial
curl -X PUT "https://cloudmc_endpoint/api/v2/trials/:id/activate" \
-H "MC-Api-Key: your_api_key"
Activate the trial for the provided id.
Extend trial
POST /trials/:id/extend
# Extend a trial
curl -X PUT "https://cloudmc_endpoint/api/v2/trials/:id/extend" \
-H "MC-Api-Key: your_api_key"
Extend the trial for the provided id.
| Query Params | |
|---|---|
extendDatelong |
The date in a long format to which the trial will be extend to. Default value is the expired date adding with the number of days for an extension defined in the trial settings. |
Terminal trial
POST /trials/:id/terminate
# Extend a trial
curl -X PUT "https://cloudmc_endpoint/api/v2/trials/:id/terminate" \
-H "MC-Api-Key: your_api_key"
Terminate the trial for the provided id.
| Query Params | |
|---|---|
purgeboolean |
Indicate if the trial needs to be purge as well. Default is false. |
Deny trial
POST /trials/:id/deny
# Deny a trial
curl -X PUT "https://cloudmc_endpoint/api/v2/trials/:id/deny" \
-H "MC-Api-Key: your_api_key"
Request body example:
As per client request
Deny the trial for the provided id. The body of the request is the reason for being denied.
Convert to billable
POST /trials/:id/convertToBillable
# Cnvert to billable a trial
curl -X PUT "https://cloudmc_endpoint/api/v2/trials/:id/convertToBillable" \
-H "MC-Api-Key: your_api_key"
Convert to billable the trial for the provided id.
| Query Params | |
|---|---|
billableStartDatelong |
The date time in a long format for which the trial will be converted. It is mandatory. |
Retrieve trial activities
GET /trials/:id/activity
# Retrieve trial activities
curl "https://cloudmc_endpoint/api/v2/trials/b41f2aa3-e2d1-48d8-9760-8b874c20e8ae/activity" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": [
{
"userLastname": "Doe",
"organizationId": "0518842d-1ad6-4b66-abc4-2cf48d502b4c",
"requesterIp": "127.0.0.1",
"userEmail": "john.doe@yahoo.com",
"id": "5e854a75-11d2-47ea-a1b4-df7d5886294c",
"userOrganizationId": "23910576-d29f-4c14-b663-31d728ff49a5",
"organizationName": "John Doe corpo",
"created": "2020-10-20T15:41:18.666Z",
"userId": "39f2b0ea-85f0-49a0-b005-c34fa62baf27",
"eventContext": "{...}",
"eventCode": "email_template.preview",
"userFirstname": "John",
"userOrganizationName": "System",
"category": "SYSTEM",
"updated": "2020-10-20T15:41:19.149Z",
"status": "SUCCESS",
"username": "john.doe@yahoo.com"
}
]
}
Retrieve the activities related to the trial associated to the id on the system.
| Attributes | |
|---|---|
idUUID |
The activity Id. |
organizationIdUUID |
The id of the organization impacted by the activity. |
organizationNameUUID |
The name of the organization impacted by the activity. |
userIdUUID |
The id of the person that made the activity. |
usernamestring |
The username of the person that made the activity. |
userOrganizationIdUUID |
The organization id of the user that made the activity. |
userOrganizationNamestring |
The organization name of the user that made the activity. |
userFirstNamestring |
The last name of the person that made the activity. |
userLastNamestring |
The last name of the person that made the activity. |
userEmailstring |
The email address of the person that made the activity. |
createdDatestring |
The creation date of the activity. |
updatedDatestring |
The update date of the activity. |
requesterIpstring |
The requester ip address |
parentIdUUID |
The organization object created in the system for this organization once the trial is approved. |
environmentIdUUID |
The id of the impacted environment. |
environmentNamestring |
The name of the impacted environment. |
serviceConnectionIdUUID |
The id of the impacted service connection. |
serviceConnectionNamestring |
The name of the impacted service connection. |
serviceConnectionTypestring |
The type of the impacted service connection. |
categorystring |
The category of the activity. Possible values: SYSTEM, SERVICE_OPERATION. |
statusstring |
The status of the activity. Possible values: PENDING, SUCCESS, FAILURE, PARTIAL_SUCCESS. |
eventContextstring |
Information link to the context of the activity in a JSON format. |
serviceErrorstring |
Description of an error in the service operation activities. |
apiKeyIdUUID |
The ID of the api key used to make this activity. |
apiKeyNamestring |
The name of the api key used to make this activity. |
Retrieve trial users
GET /trials/:id/users
# Retrieve trial users
curl "https://cloudmc_endpoint/api/v2/trials/b41f2aa3-e2d1-48d8-9760-8b874c20e8ae/users" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": [
{
"firstName": "John",
"lastName": "Doe",
"failedLoginCount": 0,
"id": "11391f05-3828-49d7-b7f8-eca7f353cbc2",
"userName": "john.doe@yahoo.com",
"loginCount": 0
}
]
}
Retrieve the users related to the trial associated to the id on the system.
| Attributes | |
|---|---|
idUUID |
The id of the trial. |
firstNamestring |
The first name of the user. |
lastNamestring |
The last name of the user. |
usernamestring |
The username of the user. |
failedLoginCountinteger |
The count of failed login for that user. |
loginCountinteger |
The count of successful login for that user. |
failedLoginCountinteger |
The count of failed login for that user. |
lastLoginstring |
The date of the last login |
lastFailedLoginstring |
The date of the last failed login |
Resend trial email
GET /trials/:id/resend_email
# Resend trial email
curl "https://cloudmc_endpoint/api/v2/trials/b41f2aa3-e2d1-48d8-9760-8b874c20e8ae/resend_email" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": true
}
Resend a trial email based on the status and type provided. If no email is send, it returns false.
| Query Param | |
|---|---|
emailUUID |
The type of email to resend. Possible values: validation, user_activation. |
Retrieve trial statuses
GET /trials/statuses
# Retrieve trial statuses
curl "https://cloudmc_endpoint/api/v2/trials/statuses" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": [
"SUBMITTED",
"PENDING",
"DENIED",
"ONGOING",
"EXPIRED",
"PURGED",
"CONVERTED"
]
}
Retrieve the possible trial statuses in the application.
Email Settings
List email settings
GET /email_settings
# Retrieve email settings
curl "https://cloudmc_endpoint/api/v2/email_settings" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": [
{
"mailgunPrivateKey": "VALIDPRIVATEKEY",
"smtpHost": "valid.host",
"smtpFromAddress": "valid.address@domain.com",
"smtpUsername": "valid.username@gmail.com",
"organization": {
"id": "fb1b2caf-4ca4-4c45-b094-faa84bdabc47"
},
"smtpPort": 2,
"mailgunDomain": "valid.mailgun.domain",
"smtpPassword": "coolPassword",
"smtpUseSsl": false,
"id": "dc30f9a6-1edc-11eb-92b6-0242ac120003"
}
]
}
List the email settings configured for the organization.
| Query Params | |
|---|---|
organization_idUUID |
Return only the settings for the provided organization id. If not provided, will default to the user's organization. |
| Attributes | |
|---|---|
idUUID |
The configured email settings' id. |
organization.idUUID |
The organization id that the email settings are linked to. |
smtpHoststring |
Hostname or IP address of your SMTP mail server (e.g. smtp.yourcompany.com). |
smtpFromAddressstring |
Email address used in the 'sender address' (or 'from') field. |
smtpUsernamestring |
If your SMTP host requires authentication, specify the username of these authentication credentials here. |
smtpPasswordstring |
If your SMTP host requires authentication, specify the password associated with the username you specified. |
smtpPortinteger |
SMTP port number, usually 25 for SMTP or 465 for SMTPS. |
smtpUseSslboolean |
Set to true if your SMTP host uses the SSL protocol. |
mailgunDomainstring* |
Domain name for the MailGun service. |
mailgunPrivateKeystring |
Private key for the MailGun service. |
Retrieve email settings
GET /email_settings/:id
# Retrieve knowledge base
curl "https://cloudmc_endpoint/api/v2/email_settings/dc30f9a6-1edc-11eb-92b6-0242ac120003" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": {
"mailgunPrivateKey": "VALIDPRIVATEKEY",
"smtpHost": "valid.host",
"smtpFromAddress": "valid.address@domain.com",
"smtpUsername": "valid.username@gmail.com",
"organization": {
"id": "fb1b2caf-4ca4-4c45-b094-faa84bdabc47"
},
"smtpPort": 2,
"mailgunDomain": "valid.mailgun.domain",
"smtpPassword": "coolPassword",
"smtpUseSsl": false,
"id": "dc30f9a6-1edc-11eb-92b6-0242ac120003"
}
}
Retrieve the email settings associated to the email settings id.
| Attributes | |
|---|---|
idUUID |
The configured email settings' id. |
organization.idUUID |
The organization id that the email settings are linked to. |
smtpHoststring |
Hostname or IP address of your SMTP mail server (e.g. smtp.yourcompany.com). |
smtpFromAddressstring |
Email address used in the 'sender address' (or 'from') field. |
smtpUsernamestring |
If your SMTP host requires authentication, specify the username of these authentication credentials here. |
smtpPasswordstring |
If your SMTP host requires authentication, specify the password associated with the username you specified. |
smtpPortinteger |
SMTP port number, usually 25 for SMTP or 465 for SMTPS. |
smtpUseSslboolean |
Set to true if your SMTP host uses the SSL protocol. |
mailgunDomainstring* |
Domain name for the MailGun service. |
mailgunPrivateKeystring |
Private key for the MailGun service. |
Update email settings
PUT /email_settings/:id
# Updates an existing email settings for an organization
curl -X PUT "https://cloudmc_endpoint/api/v2/email_settings/dc30f8f7-1edc-11eb-92b6-0242ac120003 \
-H "MC-Api-Key: your_api_key"
-H "Content-Type: application/json" \
-d "request-body"
Request body example:
{
"organization": {
"id": "ce77d759-c015-4a92-b594-3f7119867e1f"
},
"mailgunPrivateKey": "VALIDPRIVATEKEY",
"smtpHost": "valid.host",
"smtpFromAddress": "valid.address@domain.com",
"smtpUsername": "valid.username@gmail.com",
"smtpPort": 2,
"mailgunDomain": "valid.mailgun.domain",
"smtpPassword": "coolPassword",
"smtpUseSsl": false,
"id": "dc30f8f7-1edc-11eb-92b6-0242ac120003"
}
The above command return JSON structured like this:
{
"data": {
"mailgunPrivateKey": "VALIDPRIVATEKEY",
"smtpHost": "valid.host",
"smtpFromAddress": "valid.address@domain.com",
"smtpUsername": "valid.username@gmail.com",
"organization": {
"id": "ce77d759-c015-4a92-b594-3f7119867e1f"
},
"smtpPort": 2,
"mailgunDomain": "valid.mailgun.domain",
"smtpPassword": "coolPassword",
"smtpUseSsl": false,
"id": "dc30f8f7-1edc-11eb-92b6-0242ac120003"
}
}
Updates the email settings of an organization.
| Required | |
|---|---|
idUUID |
The configured email settings' id. |
organization.idUUID |
The organization id that the email settings are linked to. It cannot be changed. |
| Optional | |
|---|---|
smtpHoststring |
Hostname or IP address of your SMTP mail server (e.g. smtp.yourcompany.com). |
smtpFromAddressstring |
Email address used in the 'sender address' (or 'from') field. |
smtpUsernamestring |
If your SMTP host requires authentication, specify the username of these authentication credentials here. |
smtpPasswordstring |
If your SMTP host requires authentication, specify the password associated with the username you specified. |
smtpPortinteger |
SMTP port number, usually 25 for SMTP or 465 for SMTPS. |
smtpUseSslboolean |
Set to true if your SMTP host uses the SSL protocol. |
mailgunDomainstring* |
Domain name for the MailGun service. |
mailgunPrivateKeystring |
Private key for the MailGun service. |
Feedback Settings
Find feedback settings associated to an organization
GET /feedback/find?organizationId=:id
Retrieve the feedback settings associated to an organization. If the organizationId is omitted, the authenticated user's organization will be used.
# Retrieve the feedback settings
curl "https://cloudmc_endpoint/api/v2/feedback/find?organizationId=fcda8d5a-0276-4de3-908f-b3bd0aff2491" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": {
"id": "f4be2785-ec67-474c-af3a-38ffecfa4094",
"organization": {
"id": "fcda8d5a-0276-4de3-908f-b3bd0aff2491"
},
"feedbackEmail": "feedback@company.com",
"feedbackSlackWebhookUrl": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"googleTagManagerContainerId": "GTM-XXXXXXX",
"matomoHost": "https://myUrl-cloudmc.matomo.cloud/",
"matomoWebsiteId": "1",
"supportEmail": "support@company.com",
"widgetZesettings": "",
"zendeskWidgetKey": ""
}
}
Retrieve feedback settings
GET /feedback/:id
Retrieve the feedback settings associated to a feedback setting id.
# Retrieve feedback settings
curl "https://cloudmc_endpoint/api/v2/feedback/f4be2785-ec67-474c-af3a-38ffecfa4094" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": {
"id": "f4be2785-ec67-474c-af3a-38ffecfa4094",
"organization": {
"id": "fcda8d5a-0276-4de3-908f-b3bd0aff2491"
},
"feedbackEmail": "feedback@company.com",
"feedbackSlackWebhookUrl": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"googleTagManagerContainerId": "GTM-XXXXXXX",
"matomoHost": "https://myUrl-cloudmc.matomo.cloud/",
"matomoWebsiteId": "1",
"supportEmail": "support@company.com",
"widgetZesettings": "",
"zendeskWidgetKey": ""
}
}
Retrieve the feedback settings associated to the feedback settings id.
| Attributes | |
|---|---|
idUUID |
The configured feedback settings' id. |
organization.idUUID |
The organization id that the feedback settings are linked to. It cannot be changed. |
feedbackEmailstring |
Email address used for feedback. |
feedbackSlackWebhookUrlstring |
The slack webhook url used for feedback. Please refer to https://api.slack.com/messaging/webhooks. |
googleTagManagerContainerIdstring |
The Google Tag Manager Container ID used to deploy analytics and measurement tag configurations. Please refer to https://developers.google.com/tag-platform/tag-manager/web. |
matomoHoststring |
The Matomo analytics subdomain, ending in '.matomo.cloud'. |
matomoWebsiteIdstring |
The website ID which Matomo's Javascript pushes events to. |
supportEmailstring |
Email address used for support requests. |
widgetZesettingsstring |
Content of the zeSettings as a JSON for customization. Please refer to https://developer.zendesk.com/embeddables/docs/widget/settings. |
zendeskWidgetKeystring |
The key taken from the Zendesk admin page. Only one of supportEmail and zendeskWidgetKey can be set. |
Create feedback
POST /feedback
Create a new feedback settings. The support can either be through email or a Zendesk widget, but not both.
# Creates a new feedback settings
curl -X POST "https://cloudmc_endpoint/api/v2/feedback" \
-H "MC-Api-Key: your_api_key"
Request body example:
{
"id": "f4be2785-ec67-474c-af3a-38ffecfa4094",
"organization": {
"id": "fcda8d5a-0276-4de3-908f-b3bd0aff2491"
},
"feedbackEmail": "feedback@company.com",
"feedbackSlackWebhookUrl": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"googleTagManagerContainerId": "GTM-XXXXXXX",
"matomoHost": "https://myUrl-cloudmc.matomo.cloud/",
"matomoWebsiteId": "1",
"supportEmail": "",
"widgetZesettings": "{ \"webWidget\": { \"color\": { \"theme\": \"#78a300\" } } }",
"zendeskWidgetKey": "YourZendeskWidgetKey"
}
The above command return JSON structured like this:
{
"data": {
"widgetZesettings": "{ \"webWidget\": { \"color\": { \"theme\": \"#78a300\" } } }",
"supportEmail": "",
"zendeskWidgetKey": "YourZendeskWidgetKey",
"organization": {
"id": "fcda8d5a-0276-4de3-908f-b3bd0aff2491"
},
"feedbackSlackWebhookUrl": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"matomoHost": "https://myUrl-cloudmc.matomo.cloud/",
"id": "f4be2785-ec67-474c-af3a-38ffecfa4094",
"matomoWebsiteId": "1",
"feedbackEmail": "feedback@company.com",
"googleTagManagerContainerId": "GTM-XXXXXXX"
}
}
| Required | |
|---|---|
idUUID |
The configured feedback settings' id. |
organization.idUUID |
The organization id that the feedback settings are linked to. It cannot be changed. |
| Optional | |
|---|---|
feedbackEmailstring |
Email address used for feedback. |
feedbackSlackWebhookUrlstring |
The slack webhook url used for feedback. Please refer to https://api.slack.com/messaging/webhooks. |
googleTagManagerContainerIdstring |
The Google Tag Manager Container ID used to deploy analytics and measurement tag configurations. Please refer to https://developers.google.com/tag-platform/tag-manager/web. |
matomoHoststring |
The Matomo analytics subdomain, ending in '.matomo.cloud'. If specified, both the host and website ID are required. |
matomoWebsiteIdstring |
The website ID which Matomo's Javascript pushes events to. If specified, both the host and website ID are required. |
supportEmailstring |
Email address used for support requests. |
widgetZesettingsstring |
Content of the zeSettings as a JSON for customization. Please refer to https://developer.zendesk.com/embeddables/docs/widget/settings. |
zendeskWidgetKeystring |
The key taken from the Zendesk admin page. Only one of supportEmail and zendeskWidgetKey can be set. |
Update feedback settings
PUT /feedback/:id
Updates the feedback settings of an organization. The support can either be through email or a Zendesk widget, but not both.
# Updates an existing feedback settings for an organization
curl -X PUT "https://cloudmc_endpoint/api/v2/feedback/f4be2785-ec67-474c-af3a-38ffecfa4094 \
-H "MC-Api-Key: your_api_key"
-H "Content-Type: application/json" \
-d "request-body"
Request body example:
{
"id": "f4be2785-ec67-474c-af3a-38ffecfa4094",
"organization": {
"id": "fcda8d5a-0276-4de3-908f-b3bd0aff2491"
},
"feedbackEmail": "feedback@company.com",
"feedbackSlackWebhookUrl": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"googleTagManagerContainerId": "GTM-XXXXXXX",
"matomoHost": "https://myUrl-cloudmc.matomo.cloud/",
"matomoWebsiteId": "1",
"supportEmail": "support@company.com",
"widgetZesettings": "",
"zendeskWidgetKey": ""
}
The above command return JSON structured like this:
{
"data": {
"id": "f4be2785-ec67-474c-af3a-38ffecfa4094",
"organization": {
"id": "fcda8d5a-0276-4de3-908f-b3bd0aff2491"
},
"feedbackEmail": "feedback@company.com",
"feedbackSlackWebhookUrl": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
"googleTagManagerContainerId": "GTM-XXXXXXX",
"matomoHost": "https://myUrl-cloudmc.matomo.cloud/",
"matomoWebsiteId": "1",
"supportEmail": "support@company.com",
"widgetZesettings": "",
"zendeskWidgetKey": ""
}
}
| Required | |
|---|---|
idUUID |
The configured feedback settings' id. |
organization.idUUID |
The organization id that the feedback settings are linked to. It cannot be changed. |
| Optional | |
|---|---|
feedbackEmailstring |
Email address used for feedback. |
feedbackSlackWebhookUrlstring |
The slack webhook url used for feedback. Please refer to https://api.slack.com/messaging/webhooks. |
googleTagManagerContainerIdstring |
The Google Tag Manager Container ID used to deploy analytics and measurement tag configurations. Please refer to https://developers.google.com/tag-platform/tag-manager/web. |
matomoHoststring |
The Matomo analytics subdomain, ending in '.matomo.cloud'. If specified, both the host and website ID are required. |
matomoWebsiteIdstring |
The website ID which Matomo's Javascript pushes events to. If specified, both the host and website ID are required. |
supportEmailstring |
Email address used for support requests. |
widgetZesettingsstring |
Content of the zeSettings as a JSON for customization. Please refer to https://developer.zendesk.com/embeddables/docs/widget/settings. |
zendeskWidgetKeystring |
The key taken from the Zendesk admin page. Only one of supportEmail and zendeskWidgetKey can be set. |
Delete feedback settings
DELETE /feedback/:id
Delete an existing feedback settings.
curl -X DELETE "https://cloudmc_endpoint/api/v2/feedback/f4be2785-ec67-474c-af3a-38ffecfa4094" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"taskId": "85df8dfb-b904-42dc-bb76-4824e6b50c83",
"taskStatus": "SUCCESS"
}
Check if feedback settings is configured for an organization
GET /feedback/exists?organizationId=:id
Checks if feedback settings is configured for an organization. If the organizationId is omitted, the authenticated user's organization will be used.
# Check if feedback settings is configured
curl "https://cloudmc_endpoint/api/v2/feedback/exists?organizationId=fcda8d5a-0276-4de3-908f-b3bd0aff2491" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{}
Check if a support email is configured for an organization
GET /support/exists?organizationId=:id
Check if a support email is configured for an organization. If the organizationId is omitted, the authenticated user's organization will be used.
# Check if support email is configured
curl "https://cloudmc_endpoint/api/v2/support/exists?organizationId=fcda8d5a-0276-4de3-908f-b3bd0aff2491" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{}
Workspace Settings
Find workspace settings associated to an organization
GET /reseller/settings/workspace/find?organizationId=:id
Retrieve the workspace settings associated to an organization. If the organizationId is omitted, the authenticated user's organization will be used.
# Retrieve the workspace settings
curl "https://cloudmc_endpoint/api/v2/reseller/settings/workspace/find?organizationId=10572c3d-16e5-450f-8af8-a01e50dc52d4" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": {
"organization": {
"id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
},
"id": "f7ad28a8-1227-44de-9785-6dbd556f3bda",
"version": 1,
"detailsViewSummaryFieldsLayout": "CONDENSED",
"supportsMultiStep": false,
}
}
Retrieve the workspace settings associated to an organization.
| Attributes | |
|---|---|
idUUID |
The configured workspace settings' id. |
organization.idUUID |
The organization id that the workspace settings are linked to. It cannot be changed. |
versioninteger |
The workspace settings version. |
detailsViewSummaryFieldsLayoutenum |
The layout to render summary fields in detail views. It could be either "DEFAULT" or "CONDENSED". |
supportsMultiStepboolean |
If true, the operation's (create/edit) forms for the service connection of an organization will appear in multi-step mode. |
Retrieve workspace settings
GET /reseller/settings/workspace/:id
# Retrieve workspace settings
curl "https://cloudmc_endpoint/api/v2/reseller/settings/workspace/f7ad28a8-1227-44de-9785-6dbd556f3bda" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": {
"organization": {
"id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
},
"id": "f7ad28a8-1227-44de-9785-6dbd556f3bda",
"version": 1,
"detailsViewSummaryFieldsLayout": "CONDENSED",
"supportsMultiStep": false,
}
}
Retrieve the workspace settings associated to the workspace settings id.
| Attributes | |
|---|---|
idUUID |
The configured workspace settings' id. |
organization.idUUID |
The organization id that the workspace settings are linked to. It cannot be changed. |
versioninteger |
The workspace settings version. |
detailsViewSummaryFieldsLayoutenum |
The layout to render summary fields in detail views. It could be either "DEFAULT" or "CONDENSED". |
supportsMultiStepboolean |
If true, the operation's (create/edit) forms for the service connection of an organization will appear in multi-step mode. |
Create workspace setting
POST /reseller/settings/workspace
Create a new workspace settings.
# Creates a new workspace settings
curl -X POST "https://cloudmc_endpoint/api/v2/reseller/settings/workspace" \
-H "MC-Api-Key: your_api_key"
Request body example:
{
"organization": {
"id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
},
"detailsViewSummaryFieldsLayout": "CONDENSED",
"supportsMultiStep": false,
}
The above command return JSON structured like this:
{
"data": {
"organization": {
"id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
},
"id": "d785ffcb-9b03-478d-a49b-52a2ccedf1b8",
"version": 1,
"detailsViewSummaryFieldsLayout": "CONDENSED",
"supportsMultiStep": false,
}
}
| Required | |
|---|---|
detailsViewSummaryFieldsLayoutenum |
The layout to render summary fields in detail views. It could be either "DEFAULT" or "CONDENSED". |
supportsMultiStepboolean |
If true, the operation's (create/edit) forms for the service connection of an organization will appear in multi-step mode. |
| Optional | |
|---|---|
organization.idUUID |
The organization id that the workspace settings are linked to. If the organizationId is omitted, the authenticated user's organization will be used. |
Update workspace settings
PUT /reseller/settings/workspace/:id
Updates the workspace settings of an organization.
# Updates an existing workspace settings for an organization
curl -X PUT "https://cloudmc_endpoint/api/v2/reseller/settings/workspace/d785ffcb-9b03-478d-a49b-52a2ccedf1b8 \
-H "MC-Api-Key: your_api_key"
-H "Content-Type: application/json" \
-d "request-body"
Request body example:
{
"organization": {
"id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
},
"id": "d785ffcb-9b03-478d-a49b-52a2ccedf1b8",
"version": 1,
"detailsViewSummaryFieldsLayout": "DEFAULT",
"supportsMultiStep": false,
}
The above command return JSON structured like this:
{
"data": {
"organization": {
"id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
},
"id": "d785ffcb-9b03-478d-a49b-52a2ccedf1b8",
"version": 2,
"detailsViewSummaryFieldsLayout": "DEFAULT",
"supportsMultiStep": false,
}
}
| Required | |
|---|---|
idUUID |
The configured workspace settings' id. |
organization.idUUID |
The organization id that the workspace settings are linked to. It cannot be changed. |
detailsViewSummaryFieldsLayoutenum |
The layout to render summary fields in detail views. It could be either "DEFAULT" or "CONDENSED". |
supportsMultiStepboolean |
If true, the operation's (create/edit) forms for the service connection of an organization will appear in multi-step mode. |
Delete workspace settings
DELETE /reseller/settings/workspace/:id
Delete an existing workspace settings.
curl -X DELETE "https://cloudmc_endpoint/api/v2/reseller/settings/workspace/d785ffcb-9b03-478d-a49b-52a2ccedf1b8" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"taskId": "26022b83-9797-44c0-883c-7e82ecb757e9",
"taskStatus": "SUCCESS"
}
Custom fields
Custom fields allow administrators to define new fields on the organization and user models. This allows for additional metadata to be defined on these models.
List custom fields
GET /custom_fields
# Retrieve custom fields
curl "https://cloudmc_endpoint/api/v2/custom_fields?organization_id=fb0eeef9-eddd-48bc-949c-871481777ff9" \
-h "Mc-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": [
{
"field": "username",
"organization": {
"id": "fb0eeef9-eddd-48bc-949c-871481777ff9"
},
"mode": "AUTOGENERATED",
"modeOptions": {
"autogeneratedType": "ALPHANUMERIC",
"prefix": "ACC-",
"length": 6
},
"id": "f9a2b02b-7d67-4910-8353-c4bfcbdeaa7e",
"type": "ORGANIZATION",
"nameTranslations": {
"en": "username",
"fr": "username fr"
},
"descriptionTranslations": {
"en": "username desc",
"fr": "username desc fr"
}
}
]
}
Retrieves a list of custom fields for the given organization.
| Query Params | |
|---|---|
organization_idUUID |
Return only the custom fileds for the provided organization id. If not provided, will default to the user's organization. |
| Attributes | |
|---|---|
idUUID |
The custom field's id. |
organization.idUUID |
The organization id that the custom field belongs to. |
fieldString |
The field you're defining, this is not the UI-facing name. |
modeenum |
The mode of the field. Possible values: REQUIRED, OPTIONAL, AUTOGENERATED. |
modeOptions.autogeneratedTypeenum |
The format followed by the autogenerated field. Possible values: ALPHANUMERIC, ALPHABETICAL, NUMERIC. |
modeOptions.prefixString |
The prefix section of the autogenerated field. |
modeOptions.lengthnumber |
The length of the autogenerated section of the field. |
typestring |
The type of model for the field. Possible values: ORGANIZATION, USER. |
nameTranslationsmap |
Map of language short codes to name translations for the field. |
descriptionTranslationsmap |
Map of language short codes to description translations for the field. |
Retrieve custom field
GET /custom_fields/:id
curl "http://cloudmc_endpoint/api/v2/custom_fields/f9a2b02b-7d67-4910-8353-c4bfcbdeaa7e" \
-h "Mc-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": {
"field": "username",
"organization": {
"id": "fb0eeef9-eddd-48bc-949c-871481777ff9"
},
"mode": "AUTOGENERATED",
"modeOptions": {
"autogeneratedType": "ALPHANUMERIC",
"prefix": "ACC-",
"length": 6
},
"id": "f9a2b02b-7d67-4910-8353-c4bfcbdeaa7e",
"type": "ORGANIZATION",
"nameTranslations": {
"en": "username",
"fr": "username fr",
"es": "username es"
},
"descriptionTranslations": {
"en": "username desc",
"fr": "username desc fr"
}
}
}
| Attributes | |
|---|---|
idUUID |
The custom field's id. |
organization.idUUID |
The organization id that the custom field belongs to. |
fieldString |
The field you're defining, this is not the UI-facing name. |
modeenum |
The mode of the field. Possible values: REQUIRED, OPTIONAL, AUTOGENERATED. |
modeOptions.autogeneratedTypeenum |
The format followed by the autogenerated field. Possible values: ALPHANUMERIC, ALPHABETICAL, NUMERIC. |
modeOptions.prefixString |
The prefix section of the autogenerated field. |
modeOptions.lengthnumber |
The length of the autogenerated section of the field. |
typestring |
The type of model for the field. Possible values: ORGANIZATION, USER. |
nameTranslationsmap |
Map of language short codes to name translations for the field. |
descriptionTranslationsmap |
Map of language short codes to description translations for the field. |
Create a custom field
POST /custom_fields
curl --request POST \
--url https://cloudmc_endpoint/api/v2/custom_fields \
--header "Content-Type: application/json" \
--header "Mc-Api-Key: your_api_key" \
--data "request_body"
Request body example:
{
"type": "ORGANIZATION",
"field": "adminEmail",
"nameTranslations": {
"en": "Administrator's email",
"fr": "Courriel de l'administrateur"
}
}
Create a new custom field.
| Required | |
|---|---|
fieldString |
The field you're defining, this is not the UI-facing name. |
nameTranslationsmap |
Map of language short codes to name translations for the field. Translations for all languages are required. |
typestring |
The type of model for the field. Possible values: ORGANIZATION, USER. You will need the Custom fields: Manage permission to execute this operation. |
| Optional | |
|---|---|
modeenum |
The mode of the field. Possible values: REQUIRED, OPTIONAL, AUTOGENERATED. Defaults to OPTIONAL. |
modeOptions.autogeneratedTypeenum |
The format followed by the autogenerated field. Possible values: ALPHANUMERIC, ALPHABETICAL, NUMERIC. Defaults to ALPHANUMERIC. |
modeOptions.prefixString |
The prefix section of the autogenerated field. |
modeOptions.lengthnumber |
The length of the autogenerated section of the field. Defaults to 8. |
descriptionTranslationsmap |
Map of language short codes to description translations for the field. If passed, translations for all languages are required. |
organization.idUUID |
The organization id that the custom fields are linked to. It cannot be changed. If not passed, will default to the calling user's organization. |
Edit a custom field
PUT /custom_fields/:id
curl --request PUT \
--url https://cloudmc_endpoint/api/v2/custom_fields/f9a2b02b-7d67-4910-8353-c4bfcbdeaa7e \
--header "Content-Type: application/json" \
--header "Mc-Api-Key: your_api_key" \
--data "request_body"
Request body example:
{
"id": "f9a2b02b-7d67-4910-8353-c4bfcbdeaa7e",
"type": "ORGANIZATION",
"field": "adminEmail",
"nameTranslations": {
"en": "Administrator's email",
"fr": "Courriel de l'administrateur"
},
"descriptionTranslations": {
"en": "username desc",
"fr": "username desc fr"
},
"organization": {
"id": "2e481375-98e6-4963-adee-5067584f1580"
}
}
Edit an existing custom field.
| Required | |
|---|---|
idUUID |
The ID of the custom field. |
fieldString |
The field you're defining, this is not the UI-facing name. It cannot be changed. |
nameTranslationsmap |
Map of language short codes to name translations for the field. Translations for all languages are required. |
typestring |
The type of model for the field. Possible values: ORGANIZATION, USER. It cannot be changed. |
organization.idUUID |
The organization id that the custom fields are linked to. It cannot be changed. |
| Optional | |
|---|---|
modeenum |
The mode of the field. Possible values: REQUIRED, OPTIONAL, AUTOGENERATED. Defaults to OPTIONAL. |
modeOptions.autogeneratedTypeenum |
The format followed by the autogenerated field. Possible values: ALPHANUMERIC, ALPHABETICAL, NUMERIC. Defaults to ALPHANUMERIC. |
modeOptions.prefixString |
The prefix section of the autogenerated field. |
modeOptions.lengthnumber |
The length of the autogenerated section of the field. Defaults to 8. |
descriptionTranslationsmap |
Map of language short codes to description translations for the field. If passed, translations for all languages are required. |
Delete a custom field
DELETE /custom_fields/:id
curl --request DELETE \
--url https://cloudmc_endpoint/api/v2/custom_fields/f9a2b02b-7d67-4910-8353-c4bfcbdeaa7e \
--header "Content-Type: application/json" \
--header "Mc-Api-Key: your_api_key"
Delete a custom field.
Quotas
Quotas are used to limit the resource usage on a service connection consumed by an organization. The primary use case for CloudMC is to enforce limited quotas on trial accounts. Quotas can target different resources. For example, number of vCPUs, allocated memory, disk size, network bandwidth, number of public IPs and more.
List quotas
GET /quotas?organization_id=:id&type=[owned|assigned]
Retrieves a list of quotas configured for a given organization. An optional type can be specified to retrieve either only the assigned or owned quotas.
Query Parameters
| Optional | |
|---|---|
organization_idUUID |
The organization id for which we want to get the quotas from. When not specified, the quotas for the organization the current user is associated to will be returned. |
typeUUID |
The type of quotas. This can be assigned (quotas assigned to an organization) or owned (quotas managed by an organization). When not specified, both types are returned. |
# Retrieve quotas list
curl "https://cloudmc_endpoint/api/v2/quotas" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": [
{
"ownerOrganization": {
"name": "System",
"id": "a21debb5-b4ac-4e4b-9491-d0f4df6cd4f9"
},
"deleted": false,
"quotaDetails": [
{
"ceiling": 1.0,
"deleted": false,
"limitSize": 0,
"metricIdentifier": "metric-id",
"id": "1c005444-6ea2-4ebc-85f7-d75f5b1943d3",
"type": "INSTANCE_MEMORY",
"labelKey": "quotas.memory",
"version": 1
},
{
"ceiling": 1.0,
"deleted": false,
"limitSize": 0,
"metricIdentifier": "metric-id",
"id": "674f4755-640b-4697-87bb-8a5d03704552",
"type": "DISK_SIZE",
"labelKey": "quotas.disk_size",
"version": 1
},
{
"ceiling": 1.0,
"deleted": false,
"limitSize": 0,
"metricIdentifier": "metric-id",
"id": "691c55b5-ecaf-434d-b509-97c4fb554d1d",
"type": "INSTANCE_VCPUS",
"labelKey": "quotas.vcpus",
"version": 1
}
],
"name": "Quota Name",
"defaultForService": true,
"description": "Quota Description",
"numberOfOrganizationsAppliedTo": 1,
"id": "24330f70-9845-4851-acc0-ecd5d9b13613",
"creationDate": "2021-01-06T19:17:06.000Z",
"version": 1,
"serviceConnection": {
"serviceCode": "service-code",
"name": "service-name",
"id": "52fb6687-44cb-4db3-9e63-bdfabfe2faf1",
"type": "gcp",
"organization": {
"id": "c5305a63-d45c-422e-9b6b-72ed1c60aedc"
}
},
"defaultForTrial": true
},
]
}
An array of quotas with the following attributes are returned.
| Quota Attributes | |
|---|---|
idUUID |
The id of the quota. |
namestring |
The name of the quota. |
descriptionstring |
The description of the quota. |
creationDatestring |
The date in ISO 8601 that the quota was created. |
numberOfOrganizationsAppliedTonumber |
The number of organizations the quota is assigned to. |
defaultForServiceboolean |
Weather or not the quota is the default for service connections. |
defaultForTrialboolean |
Weather or not the quota is the default for trials. |
ownerOrganizationOrganization |
The organization that manages the quota. includes: id and name. |
serviceConnectionServiceConnection |
The service connection associated to the quota. includes: id and name. |
quotaDetailsArray [QuotaDetail] |
The quota details. |
The following table lists the attributes for QuotaDetail:
| QuotaDetail Attributes | |
|---|---|
idUUID |
The id of the quota detail. |
typestring |
The type of quota (metric). |
labelKeystring |
The key used for the label. |
metricIdentifierstring |
Id matching the metric identifiers provided by the plugin writer. |
ceilingnumber |
The ceiling value (metric). |
limitsizenumber |
DEPRECATED The maximum for the type (metric). |
Retrieve a quota
GET /quotas/:id
# Retrieve a specific quota
curl "https://cloudmc_endpoint/api/v2/quotas/:id" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": {
"ownerOrganization": {
"name": "System",
"id": "a21debb5-b4ac-4e4b-9491-d0f4df6cd4f9"
},
"deleted": false,
"quotaDetails": [
{
"ceiling": 1.0,
"deleted": false,
"limitSize": 0,
"metricIdentifier": "metric-id",
"id": "1c005444-6ea2-4ebc-85f7-d75f5b1943d3",
"type": "INSTANCE_MEMORY",
"labelKey": "quotas.memory",
"version": 1
},
{
"ceiling": 1.0,
"deleted": false,
"limitSize": 0,
"metricIdentifier": "metric-id",
"id": "674f4755-640b-4697-87bb-8a5d03704552",
"type": "DISK_SIZE",
"labelKey": "quotas.disk_size",
"version": 1
},
{
"ceiling": 1.0,
"deleted": false,
"limitSize": 0,
"metricIdentifier": "metric-id",
"id": "691c55b5-ecaf-434d-b509-97c4fb554d1d",
"type": "INSTANCE_VCPUS",
"labelKey": "quotas.vcpus",
"version": 1
}
],
"name": "Quota Name",
"defaultForService": true,
"description": "Quota Description",
"numberOfOrganizationsAppliedTo": 1,
"id": "24330f70-9845-4851-acc0-ecd5d9b13613",
"creationDate": "2021-01-06T19:17:06.000Z",
"version": 1,
"serviceConnection": {
"serviceCode": "service-code",
"name": "service-name",
"id": "52fb6687-44cb-4db3-9e63-bdfabfe2faf1",
"type": "gcp",
"organization": {
"id": "c5305a63-d45c-422e-9b6b-72ed1c60aedc"
}
},
"defaultForTrial": true
}
}
A quota with the following attributes are returned.
| Quota Attributes | |
|---|---|
idUUID |
The id of the quota. |
namestring |
The name of the quota. |
descriptionstring |
The description of the quota. |
creationDatestring |
The date in ISO 8601 that the quota was created. |
numberOfOrganizationsAppliedTonumber |
The number of organizations the quota is assigned to. |
defaultForServiceboolean |
Weather or not the quota is the default for service connections. |
defaultForTrialboolean |
Weather or not the quota is the default for trials. |
ownerOrganizationOrganization |
The organization that manages the quota. includes: id and name. |
serviceConnectionServiceConnection |
The service connection associated to the quota. includes: id and name. |
quotaDetailsArray [QuotaDetail] |
The quota details. |
The following table lists the attributes for QuotaDetail:
| QuotaDetail Attributes | |
|---|---|
idUUID |
The id of the quota detail. |
typestring |
The type of quota (metric). |
labelKeystring |
The key used for the label. |
metricIdentifierstring |
Id matching the metric identifiers provided by the plugin writer. |
ceilingnumber |
The ceiling value (metric). |
limitsizenumber |
DEPRECATED The maximum for the type (metric). |
Create a quota
POST /quotas
curl -X POST "https://cloudmc_endpoint/api/v2/quotas" \
-H "MC-Api-Key: your_api_key"
Request body example:
json { "name": "my-quota-name", "serviceConnection": { "id": "6abd9b5b-2aad-4732-9177-509d536c5739" }, "ownerOrganization": { "id": "976e1d4b-de6f-454b-a189-b12dd1b85112" }, "quotaDetails": [ { "metricIdentifier": "instance.cpu.count", "ceiling": 5 }, { "metricIdentifier": "disk.size.gb", "ceiling": 500 } ], "defaultForService": true, "defaultForTrial": true }
Create a quota owned by an organization for a connection.
Once created, a quota can be applied to any child organization of the quota's owner. This endpoint cannot be used to apply a quota to an organization. See POST /quotas/apply instead.
There can only be one default quota and one default trial quota for a connection. Any attempt to create a default quota, when there's already an existing one, will result in the exsting quota losing it's default status.
| Required | |
|---|---|
namestring |
Name of the quota. Must be unique across the connection and organization. |
serviceConnectionServiceConnection |
Service connection associated to the quota. required: id |
quotaDetailsArray[QuotaDetails] |
List of QuotaDetail making up the quota. A QuotaDetail represents a limit on a resource and is directly linked to a MetricDescriptor. A MetricDescriptor describes a metric offered by the plugin. For more information, consult the SDK documentation.required: metricIdentifier, ceiling |
quotaDetail.metricIdentifierstring |
A unique identifier used to define a MetricDescriptor. |
quotaDetail.ceilingnumber |
The ceiling for this particular quota detail. |
| Optional | |
|---|---|
ownerOrganizationOrganization |
Organization in which the quota will be created. Defaults to caller's organization. required: id |
defaultForServiceBoolean |
A flag denoting if this quota is the default quota for this connection. There can only be one default quota per connection/organization. |
defaultForTrialBoolean |
A flat denoting if this quota is the default quota for a trial. There can only be one default trial quota per connection/organization. |
The responses' data field contains the created quota with its id.
Update a quota
PUT /quotas/:id
curl -X PUT "https://cloudmc_endpoint/api/v2/quotas" \
-H "MC-Api-Key: your_api_key"
Request body example:
json { "name": "my-quota-name", "description": "Quotas for trials", "quotaDetails": [ { "metricIdentifier": "instance.cpu.count", "ceiling": 5 }, { "metricIdentifier": "disk.size.gb", "ceiling": 300 } ], }Notes: - An existing quotas, owner organization and service connection cannot be changed. - ThequotaDetailsin the request will entirely replace the previousquotaDetails. A quotaDetail for every metric enforced by the plugin must be present. - The default flags of the quota can not be changed via the update endpoint. To update these flags, the 'quotas/:id/default' should be used. - There is an asynchronous portion of this API that will assign the updated quota limits to all currently assigned organizations and organization environments on the backend service.
| Required | |
|---|---|
namestring |
Name of the quota. Must be unique across the connection and organization. |
quotaDetailsArray[QuotaDetails] |
List of QuotaDetail making up the quota. A QuotaDetail represents a limit on a resource and is directly linked to a MetricDescriptor. A MetricDescriptor describes a metric offered by the plugin. For more information, consult the SDK documentation.required: metricIdentifier, ceiling |
quotaDetail.metricIdentifierstring |
A unique identifier used to define a MetricDescriptor. |
quotaDetail.ceilingnumber |
The ceiling for this particular quota detail. |
| Optional | |
|---|---|
descriptionString |
The description of this quota |
The responses' data field contains the updated quota.
The above command returns a JSON structured like this:
{
"taskId": "085b008e-7ee4-444b-8092-350190786147",
"taskStatus": "PENDING",
"data":{
"ownerOrganization":{
"name":"Cox Communications",
"id":"ca785487-5e22-4bac-ab01-187260b0d0cb"
},
"quotaDetails":[
{
"ceiling":12.0,
"limitSize":12,
"metricIdentifier":"workload_cpu_count",
"metricDescriptor":{
"metricIdentifier":"workload_cpu_count",
"nameLabelKey":"metrics.quotas.workload_cpu_count",
"unitLabelKey":"metrics.units.unit",
"categoryLabelKey":"usage.stackpath.compute",
"resourceMetricType":"GAUGE"
},
"id":"04d7c0cb-455a-42b2-b32a-b914c871a598",
"type":"workload_cpu_count",
"labelKey":"workload_cpu_count.label"
}
],
"description":"Trials assigned Edge Cloud should be assigned this quota",
"numberOfOrganizationsAppliedTo":0,
"creationDate":"2021-03-10T16:37:02.000Z",
"defaultForTrial":true,
"name":"Trial",
"organizations":[],
"defaultForService":false,
"id":"6c44dc22-abf9-4fa2-b722-751848f1858e",
"serviceConnection":{
"serviceCode":"edge-cloud-beta",
"organization":{
"id":"ca785487-5e22-4bac-ab01-187260b0d0cb"
},
"name":"Edge Cloud Beta",
"id":"081ffa1f-1531-4dd5-a7e2-070e560409ce",
"type":"stackpath"
}
}
},
| Attributes | |
|---|---|
taskIdUUID |
The id of the asynchronous task |
taskStatusstring |
The current status of the asynchronous task |
dataQuota |
The updated quota model |
Delete a quota
DELETE /quotas/:id1?quota_id=:id2
Deletes an existing quota. The parameter quota_id is only required when deleting a quota that is currently assigned to an organization.
# Delete a specific quota
curl -X DELETE "https://cloudmc_endpoint/api/v2/quotas/:id" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"taskId": "085b008e-7ee4-444b-8092-350190786147",
"taskStatus": "SUCCESS"
}
Query Parameters
| Optional | |
|---|---|
quota_idUUID |
The id of the quota that will be used as a substitution for the quota that is being deleted. |
Assign quota to be default quota
POST /quotas/:quota_id?service=true&trial=false
Makes a quota with :quota_id the default for the a service, trial or both. A quota can only be set as default if the quota is owned by the connection owner.
# Makes a specific quota default
curl -X POST "https://cloudmc_endpoint/api/v2/quotas/:id/default?service=true&trial=false" \
-H "MC-Api-Key: your_api_key"
The above command returns the updated quota when it was successfully made a default for service or trial.
Note: This endpoint only attempts to set the quota as the default, it does not remove the default flag of the quota
if both service and trial query parameters are false.
{
"data": {
"ownerOrganization": {
"name": "System",
"id": "a21debb5-b4ac-4e4b-9491-d0f4df6cd4f9"
},
"deleted": false,
"quotaDetails": [
{
"ceiling": 1.0,
"deleted": false,
"limitSize": 0,
"metricIdentifier": "metric-id",
"id": "1c005444-6ea2-4ebc-85f7-d75f5b1943d3",
"type": "INSTANCE_MEMORY",
"labelKey": "quotas.memory",
"version": 1
},
{
"ceiling": 1.0,
"deleted": false,
"limitSize": 0,
"metricIdentifier": "metric-id",
"id": "674f4755-640b-4697-87bb-8a5d03704552",
"type": "DISK_SIZE",
"labelKey": "quotas.disk_size",
"version": 1
},
{
"ceiling": 1.0,
"deleted": false,
"limitSize": 0,
"metricIdentifier": "metric-id",
"id": "691c55b5-ecaf-434d-b509-97c4fb554d1d",
"type": "INSTANCE_VCPUS",
"labelKey": "quotas.vcpus",
"version": 1
}
],
"name": "Quota Name",
"defaultForService": true,
"defaultForTrial": false,
"description": "Quota Description",
"numberOfOrganizationsAppliedTo": 1,
"id": "24330f70-9845-4851-acc0-ecd5d9b13613",
"creationDate": "2021-01-06T19:17:06.000Z",
"version": 1,
"serviceConnection": {
"serviceCode": "service-code",
"name": "service-name",
"id": "52fb6687-44cb-4db3-9e63-bdfabfe2faf1",
"type": "gcp",
"organization": {
"id": "c5305a63-d45c-422e-9b6b-72ed1c60aedc"
}
}
}
}
Query Parameters
| Optional | |
|---|---|
serviceboolean |
Indicates if this quota should be made the default quota for all organizations assigned this service connection. |
trialboolean |
Indicates if this quota should be made the default quota for all trial organization assigned this service connection. |
Activity
Whenever there is an event that occurs under the Administration panel for an organization (e.g: a user added to the organization, a role assigned to a user, etc.) an activity event is created.
The activity chart display the activity per day over the last 30 days.
List activity per organization
GET /activity
Retrieve activity count grouped by organization.
# Retrieve activity per organization
curl "https://cloudmc_endpoint/api/v2/organizations/activity" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": {
"afd011d5-c7dd-4763-9892-ccbdafcd273b":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,21,23,27,0,0,3],
"37088fe3-b266-4283-a8d0-7ff78e476760":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,7],
"3c733655-c520-49e8-97f1-150d78d07fa5":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,16,0,0,0,0,0]
}
}
where the key is the organization UUID and the value is an array of integer representing daily activity. The size of the array of integer represents each day over a period of 30 days, relative to today.
Activity Logs
Activity logs are used to view the different audited operations on a given organization.
List activities
GET /activity_log
Retrieves a list of activities on a given organization. Optional parameters organizationId and only_mine can be specified to narrow the list of activities being returned.
| Optional Query Parameters | |
|---|---|
organizationIdUUID |
The organization id for which we want to get the activities from. When not specified, the activities for the organization the current user is associated to will be returned. |
only_mineboolean |
Indicates if the list should include only activities performed by the current user. When not specified, the value is false. |
includeSubOrgsboolean |
Indicates if the list should include the sub-organizations. When not specified, the value is false. |
environmentIdUUID |
The environment id for which we want to get the activities from. When not specified, all environments will be returned. |
serviceConnectionIdUUID |
The environment id for which we want to get the activities from. When not specified, all environments will be returned. |
userIdUUID |
The user id for which we want to get the activities from. When not specified, all users will be returned. |
categorystring |
The category for which we want to get the activities from. When not specified, all categories will be returned. |
eventCodestring |
The event code for which we want to get the activities from. When not specified, all event codes will be returned. |
statusstring |
The status for which we want to get the activities from. When not specified, all statuses will be returned. |
startdate |
The start timestamp in RFC3339 text format which which we want to get the activities from. When not specified, all events will be returned. |
enddate |
The end timestamp in RFC3339 text format which which we want to get the activities from. When not specified, all events will be returned. |
# Retrieve activity list
curl "https://cloudmc_endpoint/api/v2/activity_log" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": [
{
"userLastname": "Name",
"organizationId": "856ed38e-da4a-4f51-a7ad-e4981a44c66c",
"requesterIp": "127.0.0.1",
"userEmail": "username@acme.com",
"correlationId": "caa1445a-99d4-4ec2-a6d0-13ea29f12b09",
"id": "000598f3-d538-4b18-a5e7-964696ef8d79",
"userOrganizationId": "a21debb5-b4ac-4e4b-9491-d0f4df6cd4f9",
"organizationName": "Acme",
"created": "2021-02-02T14:12:39.422Z",
"userId": "0d7baac6-885a-4c82-9656-77529213223e",
"eventContext": "{\"id\":null,\"firstName\":\"User\",\"lastName\":\"Name\",\"userName\":\"username@acme.com\",\"timezone\":null,\"status\":null,\"organization\":{\"id\":\"856ed38e-da4a-4f51-a7ad-e4981a44c66c\",\"name\":\"Acme\",\"isDbAuthentication\":true},\"locale\":\"en\",\"email\":\"username@acme.com\",\"lastLogin\":null,\"lastFailedLogin\":null,\"loginCount\":null,\"isTechnicalContact\":null,\"isBusinessContact\":null,\"creationDate\":null,\"tfaEnabled\":false,\"receivesEmailNotifications\":true,\"primaryRoleBinding\":{\"id\":null,\"role\":{\"id\":\"e292f73b-99ff-4677-9aeb-d98b3e196089\",\"name\":\"guest\",\"isFixed\":true,\"isSystem\":true},\"organization\":{\"id\":\"856ed38e-da4a-4f51-a7ad-e4981a44c66c\"}}}",
"eventCode": "users.created",
"userFirstname": "User",
"userOrganizationName": "System",
"category": "SYSTEM",
"updated": "2021-02-02T14:12:43.709Z",
"status": "SUCCESS",
"username": "username"
}
]
}
An array of activities with the following attributes are returned.
| Activity Attributes | |
|---|---|
idUUID |
The id of the activity. |
correlationIdUUID |
The correlation id of the activity. |
eventCodestring |
The human readable code for the event. |
categorystring |
The category the event belongs to. |
statusstring |
The status of the event. |
createdstring |
The date in ISO 8601 that the activity was created. |
updatedstring |
The date in ISO 8601 that the activity was created. |
userIdUUID |
The id of the user who generated the activity. |
usernamestring |
The username of the user who generated the activity. |
userFirstnamestring |
The first name of the user who generated the activity. |
userLastnamestring |
The first name of the user who generated the activity. |
userEmailstring |
The email of the user who generated the activity. |
userOrganizationIdUUID |
The id of the organization of the user who generated the activity. |
userOrganizationNamestring |
The name of the organization of the user who generated the activity. |
organizationIdUUID |
The id of the organization of activity belongs to. |
organizationNamestring |
The name of the organization of activity belongs to. |
requesterIpstring |
The ip address of the requester. |
eventContextstring |
The escaped json event context. |
List activity codes
GET /activity_log/codes
Retrieves a list of activity codes. Optional parameters organizationId and include_subs can be specified to narrow the list of activities being returned.
| Optional Query Parameters | |
|---|---|
organizationIdUUID |
The organization id for which we want to get the activity codes from. When not specified, the activity codes for the organization the current user is associated to will be returned. |
include_subsboolean |
If we want to include sub-organizations activity codes. |
# Retrieve activity codes
curl "https://cloudmc_endpoint/api/v2/activity_log/codes" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": {
"SYSTEM": [
"res_commitments.update",
"users.autocreated",
"environment_members.purge",
"custom_field.deleted",
"organizations.provision",
"trials.converted_to_billable",
// ...
]
}
}
The list of activity codes is returned grouped by category.
Get activities summary
GET /activity_log/summary
Retrieves a summary of activities. An optional maxNumberOfItems can be passed to narrow the number of items down to be included in the summary.
| Optional Query Parameters | |
|---|---|
maxNumberOfItemsnumber |
The number of items to be included in the summary. |
# Retrieve activities summary
curl "https://cloudmc_endpoint/api/v2/activity_log/summary" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": [
{
"userLastname": "Name",
"organizationId": "829f0117-4b1f-49bb-8daf-ea4625ea6133",
"environmentId": "e721bb72-e332-4745-b72f-0b15633d2823",
"serviceConnectionName": "service-connection-name",
"environmentName": "env-local",
"userEmail": "username@acme.com",
"id": "2fd514fb-bdb8-481c-ad0c-7da683181df5",
"userOrganizationId": "829f0117-4b1f-49bb-8daf-ea4625ea6133",
"serviceConnectionType": "stackpath",
"organizationName": "System",
"created": "2021-03-11T18:45:01.486Z",
"userId": "ff17986e-8a66-4e23-8cb1-f846b1c1deb6",
"parentId": "f5b77da1-9539-446b-8399-94c034604b0f",
"eventContext": "{\"userName\":\"username@acme.com\",\"environmentName\":\"env-local\",\"organizationName\":\"Acme\",\"connectionName\":\"service-connection-name\"}",
"eventCode": "environment_members.provision",
"serviceConnectionId": "8c77bf1a-3eca-4509-b13d-005bf779df28",
"userFirstname": "User",
"userOrganizationName": "System",
"category": "SYSTEM",
"updated": "2021-03-11T18:45:02.340Z",
"status": "SUCCESS",
"username": "username@acme.com"
}
]
}
An array of activity summaries with the following attributes are returned.
| Activity Summary Attributes | |
|---|---|
idUUID |
The id of the activity. |
parentIdUUID |
The id of the parent activity. |
eventCodestring |
The human readable code for the activity event. |
categorystring |
The category the activity event belongs to. |
statusstring |
The status of the activity event. |
createdstring |
The date in ISO 8601 that the activity was created. |
updatedstring |
The date in ISO 8601 that the activity was created. |
userIdUUID |
The id of the user who generated the activity. |
usernamestring |
The username of the user who generated the activity. |
userFirstnamestring |
The first name of the user who generated the activity. |
userLastnamestring |
The first name of the user who generated the activity. |
userEmailstring |
The email of the user who generated the activity. |
userOrganizationIdUUID |
The id of the organization of the user who generated the activity. |
userOrganizationNamestring |
The name of the organization of the user who generated the activity. |
organizationIdUUID |
The id of the organization the activity belongs to. |
organizationNamestring |
The name of the organization of activity belongs to. |
environmentIdUUID |
The id of the environment the activity belongs to. |
environmentNamestring |
The name of the environment the activity belongs to. |
eventContextstring |
The escaped json event context. |
serviceConnectionIdUUID |
The id of the service connection the activity belongs to. |
serviceConnectionNamestring |
The name of the service connection the activity belongs to. |
serviceConnectionTypestring |
The type of the service connection the activity belongs to. |
Billing
Billing Settings
Find billing settings associated to an organization
GET /reseller/settings/billing/find?organizationId=:id
Retrieve the billing settings associated to an organization. If the organizationId is omitted, the authenticated user's organization will be used.
# Retrieve the billing settings
curl "https://cloudmc_endpoint/api/v2/reseller/settings/billing/find?organizationId=10572c3d-16e5-450f-8af8-a01e50dc52d4" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": {
"organization": {
"id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
},
"id": "f7ad28a8-1227-44de-9785-6dbd556f3bda",
"version": 1,
"daysBeforeAutoDraft": 3,
"daysBeforeAutoApproval": 3,
"daysBeforeAutoPayment": 5,
"invoiceTag": {
"id": "f3003247-b147-4f8f-b625-bc963a6cb6e3",
"name": "non-invoiceable"
},
"bccEmails": ["finance.support@company.com", "monitoring@company.com"],
"daysBeforeCardWarnings": [30],
"customerInformation": ["accountId"],
"address": ["Address line 1", "Address line 2", "etc."],
"termsAndConditions": "My terms and conditions..."
}
}
Retrieve the billing settings associated to an organization.
| Attributes | |
|---|---|
idUUID |
The configured billing settings' id. |
organization.idUUID |
The organization id that the billing settings are linked to. It cannot be changed. |
versioninteger |
The billing settings version. |
daysBeforeAutoDraftinteger |
The number of days after the billing date to continue gathering missing customer usage before the invoice is marked in review. Cannot be less than 2 days. |
daysBeforeAutoApprovalinteger |
The number of days to review an in review invoice before it is automatically issued to the customer. |
daysBeforeAutoPaymentinteger |
The number of days after the invoice has been issued before the customer's credit card is automatically charged. |
invoiceTagobject |
Specify a tag that can be used to mark organizations as not invoiceable. |
bccEmailsArray[string] |
List of email addresses to include as BCC when sending emails to customers upon billing exceptions. |
daysBeforeCardWarningsArray[integer] |
Specify the number of days before notifying a customer of an expiring credit card. You can specify 1 to 5 values between 1 and 60. |
customerInformationArray[string] |
The list of client custom fields to display in the invoice. |
addressArray[string] |
The address to display in the invoice. Each address field will be a row in the address block. |
termsAndConditionsstring |
The terms and conditions to display in the invoice. |
Retrieve billing settings
GET /reseller/settings/billing/:id
# Retrieve billing settings
curl "https://cloudmc_endpoint/api/v2/reseller/settings/billing/f7ad28a8-1227-44de-9785-6dbd556f3bda" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data":{
"daysBeforeAutoDraft":5,
"minimumDaysInvoicePeriod":15,
"bccEmails":[
"email@cloudops.com"
],
"address":{
"country":"USA",
"province":"Georgia",
"city":"Atlanta",
"postalCode":"30328",
"businessName":"Org",
"lineOne":"123 Example Street"
},
"daysBeforeAutoApproval":3,
"version":93,
"defaultPricingPackage":{
"id":"8358f8d6-1f2d-4bb9-bb0a-f8ce51dfa19c"
},
"daysBeforeCardWarnings":[
24
],
"invoiceTag": {
"id": "f3003247-b147-4f8f-b625-bc963a6cb6e3",
"name": "non-invoiceable"
},
"termsAndConditions":"Terms",
"defaultCurrency":"USD",
"organization":{
"name":"Org",
"customFieldDefinitions":[
{
"field":"account_number",
"id":"31b7350a-3c41-4d64-b58b-c7bfbc45abbb",
"nameTranslations":{
"en":"Account Number"
},
"descriptionTranslations":{
"en":"Account number"
}
}
],
"id":"5ff3a3d8-41a8-4ca2-813f-7d5af4cfc872"
},
"billingDay":1,
"customerInformation":[
"account_number"
],
"id":"0ada48d2-2c3b-4930-8427-d0087ec32551",
"daysBeforeAutoPayment":1
}
}
Retrieve the billing settings associated to the billing settings id.
| Attributes | |
|---|---|
idUUID |
The configured billing settings' id. |
organization.idUUID |
The organization id that the billing settings are linked to. It cannot be changed. |
organization.namestring |
The name of the organization that the billing settings are linked to. It cannot be changed. |
organization.customFieldDefinitionsArray[object] |
The defined custom field of a customer, contains the field name, id, and translation data. Only returned if the org has custom fields enabled and present. |
versioninteger |
The billing settings version. |
defaultCurrencystring |
The currency that will be used by default on an invoice. |
defaultPricingPackage.idUUID |
The pricing package id that is used to derive the usage data costs for non-billable organizations, usage reports will be available to view but invoices will not be generated for non-billable organizations. |
billingDayinteger |
The day of the month in which new billing cycles are started. |
daysBeforeAutoDraftinteger |
The number of days after the billing date to continue gathering missing customer usage before the invoice is marked in review. Cannot be less than 2 days. |
daysBeforeAutoApprovalinteger |
The number of days to review an in review invoice before it is automatically issued to the customer. |
daysBeforeAutoPaymentinteger |
The number of days after the invoice has been issued before the customer's credit card is automatically charged. |
minimumDaysInvoicePeriodinteger |
The minimum amount of days an organization has been onboarded for before an invoice is generated. |
invoiceTagobject |
Specify a tag that can be used to mark organizations as not invoiceable. |
bccEmailsArray[string] |
List of email addresses to include as Blind Carbon Copy (BCC) when sending emails to customers upon billing exceptions. |
daysBeforeCardWarningsArray[integer] |
Specify the number of days before notifying a customer of an expiring credit card. You can specify 1 to 5 values between 1 and 60. |
customerInformationArray[string] |
The list of client custom fields to display in the invoice. |
addressArray[string] |
The address to display in the invoice. Each address field will be a row in the address block. |
termsAndConditionsstring |
The terms and conditions to display in the invoice. |
Create billing settings
POST /reseller/settings/billing
Create new billing settings.
# Creates a new billing settings
curl -X POST "https://cloudmc_endpoint/api/v2/reseller/settings/billing" \
-H "MC-Api-Key: your_api_key"
Request body example:
{
"organization": {
"id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
},
"daysBeforeAutoApproval": 3,
"daysBeforeAutoPayment": 5,
"daysBeforeAutoDraft": 3,
"invoiceTag": {
"name": "non-invoiceable"
},
"bccEmails": ["finance.support@company.com", "monitoring@company.com"],
"daysBeforeCardWarnings": [30],
"customerInformation": ["accountId"],
"address": ["Address line 1", "Address line 2", "etc."],
"termsAndConditions": "My terms and conditions..."
}
The above command returns JSON structured like this:
{
"data": {
"organization": {
"id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
},
"id": "d785ffcb-9b03-478d-a49b-52a2ccedf1b8",
"version": 1,
"daysBeforeAutoDraft": 3,
"daysBeforeAutoApproval": 3,
"daysBeforeAutoPayment": 5,
"invoiceTag": {
"id": "f3003247-b147-4f8f-b625-bc963a6cb6e3",
"name": "non-invoiceable"
},
"bccEmails": ["finance.support@company.com", "monitoring@company.com"],
"daysBeforeCardWarnings": [30],
"customerInformation": ["accountId"],
"address": ["Address line 1", "Address line 2", "etc."],
"termsAndConditions": "My terms and conditions..."
}
}
| Required | |
|---|---|
daysBeforeAutoDraftinteger |
The number of days after the billing date to continue gathering missing customer usage before the invoices is marked in review. Cannot be less than 2 days. |
daysBeforeAutoApprovalinteger |
The number of days to review an in review invoice before it is automatically issued to the customer. |
daysBeforeAutoPaymentinteger |
The number of days after the invoice has been issued before the customer's credit card is automatically charged. |
daysBeforeCardWarningsArray[integer] |
Specify the number of days before notifying a customer of an expiring credit card. You can specify 1 to 5 values between 1 and 60. |
| Optional | |
|---|---|
organization.idUUID |
The organization id that the billing settings are linked to. If the organizationId is omitted, the authenticated user's organization will be used. |
defaultPricingPackage.idUUID |
The id of the default pricing package, if there is none specified then usage from non-billable organizations will not be derived a cost. |
customerInformationArray[string] |
The list of client custom fields to display in the invoice. |
addressArray[string] |
The address to display in the invoice. Each address field will be a row in the address block. |
termsAndConditionsstring |
The terms and conditions to display in the invoice. |
invoiceTagobject |
Specify a tag that can be used to mark organizations as not invoiceable. |
bccEmailsArray[string] |
List of email addresses to include as BCC when sending emails to customers upon billing exceptions. |
Update billing settings
PUT /reseller/settings/billing/:id
Updates the billing settings of an organization.
# Updates an existing billing settings for an organization
curl -X PUT "https://cloudmc_endpoint/api/v2/reseller/settings/billing/d785ffcb-9b03-478d-a49b-52a2ccedf1b8 \
-H "MC-Api-Key: your_api_key"
-H "Content-Type: application/json" \
-d "request-body"
Request body example:
{
"organization": {
"id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
},
"id": "d785ffcb-9b03-478d-a49b-52a2ccedf1b8",
"version": 1,
"daysBeforeAutoDraft": 3,
"daysBeforeAutoApproval": 3,
"daysBeforeAutoPayment": 5,
"invoiceTag": {
"id": "f3003247-b147-4f8f-b625-bc963a6cb6e3",
"name": "non-invoiceable"
},
"bccEmails": ["finance.support@company.com", "monitoring@company.com"],
"daysBeforeCardWarnings": [30],
"customerInformation": ["accountId"],
"address": ["Address line 1", "Address line 2", "etc."],
"termsAndConditions": "My terms and conditions..."
}
The above command returns JSON structured like this:
{
"data": {
"organization": {
"id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
},
"id": "d785ffcb-9b03-478d-a49b-52a2ccedf1b8",
"version": 2,
"daysBeforeAutoDraft": 3,
"daysBeforeAutoApproval": 3,
"daysBeforeAutoPayment": 5,
"invoiceTag": {
"id": "f3003247-b147-4f8f-b625-bc963a6cb6e3",
"name": "non-invoiceable"
},
"bccEmails": ["finance.support@company.com", "monitoring@company.com"],
"daysBeforeCardWarnings": [30],
"customerInformation": ["accountId"],
"address": ["Address line 1", "Address line 2", "etc."],
"termsAndConditions": "My terms and conditions..."
}
}
| Required | |
|---|---|
idUUID |
The configured billing settings' id. |
organization.idUUID |
The organization id that the billing settings are linked to. It cannot be changed. |
daysBeforeAutoDraftinteger |
The number of days after the billing date to continue gathering missing customer usage before the invoice is marked in review. Cannot be less than 2 days. |
daysBeforeAutoApprovalinteger |
The number of days to review an in review invoice before it is automatically issued to the customer. |
daysBeforeAutoPaymentinteger |
The number of days after the invoice has been issued before the customer's credit card is automatically charged. |
daysBeforeCardWarningsArray[integer] |
Specify the number of days before notifying a customer of an expiring credit card. You can specify 1 to 5 values between 1 and 60. |
| Optional | |
|---|---|
defaultPricingPackage.idUUID |
The id of the default pricing package, if there is none specified then usage from non-billable organizations will not be derived a cost. |
customerInformationArray[string] |
The list of client custom fields to display in the invoice. |
addressArray[string] |
The address to display in the invoice. Each address field will be a row in the address block. |
termsAndConditionsstring |
The terms and conditions to display in the invoice. |
invoiceTagobject |
Specify a tag that can be used to mark organizations as not invoiceable. |
bccEmailsArray[string] |
List of email addresses to include as BCC when sending emails to customers upon billing exceptions. |
Delete billing settings
DELETE /reseller/settings/billing/:id
Delete an existing billing settings.
curl -X DELETE "https://cloudmc_endpoint/api/v2/reseller/settings/billing/d785ffcb-9b03-478d-a49b-52a2ccedf1b8" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"taskId": "26022b83-9797-44c0-883c-7e82ecb757e9",
"taskStatus": "SUCCESS"
}
Billing providers
The billing providers are the different payment processing tools that can be used to charge organizations.
List billing providers
GET /billing_providers
Retrieves a list of billing providers configured in the system.
# Retrieve billing providers list
curl "https://cloudmc_endpoint/api/v2/billing_providers" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "f26e66a4-755c-4867-b565-ad68aa515237",
"organization": {
"id": "23910576-d29f-4c14-b663-31d728ff49a5"
},
"name": "Chase Credit Card (Dev)",
"type": "CREDIT_CARD",
"providerType": "chaseCreditCard",
"createdDate": "2021-05-07T19:21:20Z",
"updatedDate": "2021-05-07T19:21:20Z",
"defaultForType": true,
"configurationAttributes": {
"creditCards": "American Express,Mastercard,Visa,Discover"
}
}
]
}
| Attributes | |
|---|---|
idUUID |
The UUID of the billing provider. |
organization.idUUID |
UUID of the organization to which belongs the billing provider. This can only be a organization which is root or reseller. |
namestring |
The name of the billing provider object. |
typestring |
The type of billing provider. Possible values are: CREDIT_CARD. |
providerTypestring |
The provider for the associated type. |
createdDatestring |
The date the billing provider was created. |
updatedDatestring |
The last date the billing provider was updated. |
defaultForTypeboolean |
If this billing provider is the default for the specified type. |
configurationAttributesObject |
The configuration attribute associated to the provider type. See possible values |
Retrieve a billing provider
GET /billing_providers/:id
Retrieve a billing provider's details.
# Retrieve a billing provider's details
curl "https://cloudmc_endpoint/api/v2/billing_providers/f26e66a4-755c-4867-b565-ad68aa515237" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": {
"id": "f26e66a4-755c-4867-b565-ad68aa515237",
"organization": {
"id": "23910576-d29f-4c14-b663-31d728ff49a5"
},
"name": "Chase Credit Card (Dev)",
"type": "CREDIT_CARD",
"providerType": "chaseCreditCard",
"createdDate": "2021-05-07T19:21:20Z",
"updatedDate": "2021-05-07T19:21:20Z",
"defaultForType": true,
"configurationAttributes": {
"creditCards": "American Express,Mastercard,Visa,Discover"
}
}
}
| Attributes | |
|---|---|
idUUID |
The UUID of the billing provider. |
organization.idUUID |
UUID of the organization to which belongs the billing provider. This can only be a organization which is root or reseller. |
namestring |
The name of the billing provider object. |
typestring |
The type of billing provider. Possible values are: CREDIT_CARD. |
providerTypestring |
The provider for the associated type. |
createdDatestring |
The date the billing provider was created. |
updatedDatestring |
The last date the billing provider was updated. |
defaultForTypeboolean |
If this billing provider is the default for the specified type. |
configurationAttributesObject |
The configuration attribute associated to the provider type. See possible values |
Create a billing provider
POST /billing_providers
Create a new billing provider.
# Creates a new billing provider
curl -X POST "https://cloudmc_endpoint/api/v2/billing_providers" \
-H "MC-Api-Key: your_api_key"
Request body example:
{
"name": "Chase Credit Card (Dev)",
"organization": {
"id": "23910576-d29f-4c14-b663-31d728ff49a5"
},
"type": "CREDIT_CARD",
"providerType": "chaseCreditCard",
"defaultForType": false,
"configurationAttributes": {
"creditCards": "Visa, Mastercard, American Express, Discover"
}
}
The above command return JSON structured like this:
{
"data": {
"createdDate": "2021-05-17T19:59:33.387453Z",
"organization": {
"id": "23910576-d29f-4c14-b663-31d728ff49a5"
},
"name": "testing API",
"configurationAttributes": {
"creditCards": "Visa, Mastercard, American Express, Discover"
},
"defaultForType": false,
"id": "8db7cd13-b309-4fb9-b022-1632dbd165d0",
"updatedDate": "2021-05-17T19:59:33.387477Z",
"type": "CREDIT_CARD",
"providerType": "chaseCreditCard"
}
}
| Required | |
|---|---|
namestring |
The name of the billing provider object. |
organization.idUUID |
UUID of the organization to which belongs the billing provider. This can only be a organization which is root or reseller. |
typestring |
The type of billing provider. Possible values are: CREDIT_CARD. |
providerTypestring |
The provider for the associated type. |
configurationAttributesObject |
The configuration attribute associated to the provider type. See possible values |
| Optional | |
|---|---|
defaultForTypeUUID |
If this billing provider is the default for the specified type. |
Update billing provider
PUT /billing_providers/:id
Update an existing billing provider.
# Updates an existing billing provider
curl -X PUT "https://cloudmc_endpoint/api/v2/billing_providers/c84cfe41-929b-47c9-bde4-b55a10bd2774" \
-H "MC-Api-Key: your_api_key"
Request body example:
{
"name": "Chase Credit Card (Dev)",
"organization": {
"id": "23910576-d29f-4c14-b663-31d728ff49a5"
},
"type": "CREDIT_CARD",
"providerType": "chaseCreditCard",
"defaultForType": false,
"configurationAttributes": {
"creditCards": "Visa, Mastercard, American Express, Discover"
}
}
The above command return JSON structured like this:
{
"data": {
"createdDate": "2021-05-17T20:32:07Z",
"organization": {
"id": "23910576-d29f-4c14-b663-31d728ff49a5"
},
"name": "Chase Credit Card (Dev)",
"configurationAttributes": {
"creditCards": "Visa, Mastercard, American Express"
},
"defaultForType": false,
"id": "c84cfe41-929b-47c9-bde4-b55a10bd2774",
"updatedDate": "2021-05-17T21:09:49Z",
"type": "CREDIT_CARD",
"providerType": "chaseCreditCard"
}
}
| Required | |
|---|---|
namestring |
The name of the billing provider object. |
organization.idUUID |
UUID of the organization to which belongs the billing provider. This can only be a organization which is root or reseller. |
typestring |
The type of billing provider. Possible values are: CREDIT_CARD. |
providerTypestring |
The provider for the associated type. |
configurationAttributesObject |
The configuration attribute associated to the provider type. See possible values |
| Optional | |
|---|---|
defaultForTypeboolean |
If this billing provider is the default for the specified type. |
Provider type configuration attribute
Here are the attributes for the CREDIT_CARD providers.
| Provider | Attributes | |
|---|---|---|
| all | creditCardsstring |
The type of credit card accepted. This is a comma separated field. Possible values are 'Visa', 'Mastercard', 'American Express', 'Discover. |
| chaseCreditCard | hostnamestring |
Hosted payment hostname. |
| chaseCreditCard | secureIdstring |
Unique value identifying the client’s Hosted Payment account. |
| chaseCreditCard | secureTokenstring |
Unique value associated with Hosted Payment account. |
| chaseCreditCard | cssURLstring |
Sets the URL of the CSS file used to style the payment form. This value overrides the URL set in the Hosted Payment Page Admin screen. |
| chaseCreditCard | orbitalHostnamestring |
Orbital API hostname. |
| chaseCreditCard | orbitalUsernamestring |
Orbital Connection Username set up on Orbital Gateway. |
| chaseCreditCard | orbitalPasswordstring |
Orbital Connection Password used in conjunction with Orbital Username. |
| chaseCreditCard | orbitalMerchantIdstring |
Orbital API merchant ID. |
| chaseCreditCard | orbitalMerchantTerminalstring |
Orbital API merchant terminal ID. |
| chaseCreditCard | orbitalMerchantBinstring |
Orbital API merchant BIN number. |
Delete a billing provider
DELETE /billing_providers/:id
curl --request DELETE \
--url https://cloudmc_endpoint/api/v2/billing_providers/f9a2b02b-7d67-4910-8353-c4bfcbdeaa7e \
--header "Content-Type: application/json" \
--header "Mc-Api-Key: your_api_key"
Delete a billing provider.
Tax providers
A tax provider enables a reseller to map tax codes to monetization products. The tax code provider will ensure that invoices include taxes based on the billing details (i.e. billing address) and mapping of tax codes to product offerings provided by the reseller.
List tax providers
GET /tax_providers
Retrieves a list of tax providers configured for a reseller.
Note: You must have the Reseller billing permission on the target reseller. If the caller does not have the correct permissions or the reseller with the ID provided does not exist then a
404 Not Foundresponse will be returned.
# Retrieve tax providers
curl "https://cloudmc_endpoint/api/v2/tax_providers?reseller_id=23910576-d29f-4c14-b663-31d728ff49a5" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "f26e66a4-755c-4867-b565-ad68aa515237",
"reseller": {
"id": "23910576-d29f-4c14-b663-31d728ff49a5"
},
"type": "AVALARA",
"createdDate": "2021-05-07T19:21:20Z",
"updatedDate": "2021-05-07T19:21:20Z",
"configurationAttributes": {
"companyId": "acme",
"username": "username",
"password" "password"
}
}
]
}
| Attributes | |
|---|---|
idUUID |
The UUID of the tax provider. |
reseller.idUUID |
UUID of the reseller to which the tax provider belongs (AKA an organization id that is a reseller). |
typestring |
The type of tax provider. Possible values are: AVALARA. |
state*enum" |
The state of the tax provider. Possible values are: CONFIGURED, CONFIGURING, ERROR. |
createdDatestring |
The date the tax provider was created. |
updatedDatestring |
The last date the tax provider was updated. |
configurationAttributesObject |
The configuration attributes associated to the provider type. This depends on the provider type. |
Get a tax provider
GET /tax_providers/:id
Retrieves a tax provider's details.
Note: You must have the Reseller billing permission on the owner of the tax provider requested. If the caller does not have the correct permissions or the tax provider for the given ID does not exist, then a
404 Not Foundresponse will be returned.
# Retrieve a specific tax provider
curl "https://cloudmc_endpoint/api/v2/tax_providers/f26e66a4-755c-4867-b565-ad68aa515237" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": {
"id": "f26e66a4-755c-4867-b565-ad68aa515237",
"reseller": {
"id": "23910576-d29f-4c14-b663-31d728ff49a5"
},
"type": "AVALARA",
"createdDate": "2021-05-07T19:21:20Z",
"updatedDate": "2021-05-07T19:21:20Z",
"configurationAttributes": {
"companyId": "acme",
"username": "username",
"password" "password"
}
}
}
| Attributes | |
|---|---|
idUUID |
The UUID of the tax provider. |
reseller.idUUID |
UUID of the reseller to which the tax provider belongs (AKA an organization id that is a reseller). |
typestring |
The type of tax provider. Possible values are: AVALARA. |
state*enum" |
The state of the tax provider. Possible values are: CONFIGURED, CONFIGURING, ERROR. |
createdDatestring |
The date the tax provider was created. |
updatedDatestring |
The last date the tax provider was updated. |
configurationAttributesObject |
The configuration attributes associated to the provider type. This depends on the provider type. |
Get tax codes for a given reseller organization
GET /tax_providers/:id/tax-codes
Retrieves a list of tax codes from the configured tax provider for a reseller organization.
Note: You must have the Reseller billing permission on the owner of the tax provider requested. If the caller does not have the correct permissions or the tax provider is not configured for the given organization ID or the organization does not exist, then a
404 Not Foundresponse will be returned. The required ID in the URL is the ID of the reseller organization for which the tax codes are being fetched.
# Retrieve tax codes for a given organization
curl "https://cloudmc_endpoint/api/v2/tax_providers/f26e66a4-755c-4867-b565-ad68aa515237/tax-codes" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": [
{
"code": "SW054101",
"description": "Cloud Services - SaaS - Service Agreement - Database Products"
},
{
"code": "SW053004",
"description": "Cloud Services - SaaS - License Agreement - for business use only"
},
{
"code": "SW056003",
"description": "Cloud Services / Platform as a Service (PaaS)"
}
]
}
| Attributes | |
|---|---|
codestring |
The code of the tax. |
descriptionstring |
The description of the tax code. |
Create a tax provider
POST /tax_providers/
Creates a tax provider for the given reseller
Note: You must have the Reseller billing permission on the owner of the tax provider requested. If the caller does not have the correct permissions or the tax provider for the given ID does not exist, then a
404 Not Foundresponse will be returned.
# Create a tax provider
curl "https://cloudmc_endpoint/api/v2/tax_providers" \
-H "MC-Api-Key: your_api_key"
Request body example:
{
"reseller": {
"id": "174cace2-ad04-47c7-9429-e180bb44cf71"
},
"type": "AVALARA",
"configurationAttributes": {
"environment": "Production",
"username": "email@cloudops.com",
"password": "password",
"companyId": "1148191"
},
"address": {
"lineOne": "420 GUY ST",
"lineTwo": "",
"city": "MONTREAL",
"province": "QC",
"country": "CA",
"postalCode": "H3J 1S6"
}
}
The above command returns a JSON structured like this:
{
"data": {
"address": {
"country": "CA",
"lineTwo": "",
"province": "QC",
"city": "MONTREAL",
"postalCode": "H3J 1S6",
"lineOne": "420 GUY ST"
},
"reseller": {
"id": "174cace2-ad04-47c7-9429-e180bb44cf71"
},
"configurationAttributes": {
"environment": "Production",
"password": "password",
"companyId": "1148191",
"username": "email@cloudops.com"
},
"id": "961a2b96-0a6a-4bb4-9e32-59a3dcc555aa",
"state": "CONFIGURING",
"type": "AVALARA"
},
"taskId": "eea0cf4d-47fc-4f5d-b227-863502486192",
"taskStatus": "PENDING"
}
| Attributes | |
|---|---|
reseller.idUUID |
UUID of the reseller to which the tax provider belongs (AKA an organization id that is a reseller). |
typestring |
The type of tax provider. Possible values are: AVALARA. |
configurationAttributesObject |
The configuration attributes associated to the provider type. This depends on the provider type. |
address.lineOnestring |
The address line 1 of the reseller. |
address.lineTwostring |
The address line 2 of the reseller. |
address.citystring |
The city name of the reseller. |
address.provincestring |
The province of the reseller. |
address.countrystring |
The country of the reseller. |
address.postalCodestring |
The postal code of the reseller. |
Update a tax provider
PUT /tax_providers/:id
Updates a tax provider for the given reseller
Note: You must have the Reseller billing permission on the owner of the tax provider requested. If the caller does not have the correct permissions or the tax provider for the given ID does not exist, then a
404 Not Foundresponse will be returned.
# Update a tax provider
curl "https://cloudmc_endpoint/api/v2/tax_providers/961a2b96-0a6a-4bb4-9e32-59a3dcc555aa" \
-H "MC-Api-Key: your_api_key"
Request body example:
{
"reseller": {
"id": "174cace2-ad04-47c7-9429-e180bb44cf71"
},
"type": "AVALARA",
"configurationAttributes": {
"environment": "Production",
"username": "email@cloudops.com",
"password": "password",
"companyId": "1148191"
},
"address": {
"lineOne": "420 GUY ST",
"lineTwo": "",
"city": "MONTREAL",
"province": "QC",
"country": "CA",
"postalCode": "H3J 1S6"
}
}
The above command returns a JSON structured like this:
{
"data": {
"address": {
"country": "CA",
"lineTwo": "",
"province": "QC",
"city": "MONTREAL",
"postalCode": "H3J 1S6",
"lineOne": "420 GUY ST"
},
"reseller": {
"id": "174cace2-ad04-47c7-9429-e180bb44cf71"
},
"createdDate": "2021-05-07T19:21:20Z",
"updatedDate": "2021-05-07T19:21:20Z",
"configurationAttributes": {
"environment": "Production",
"password": "password",
"companyId": "1148191",
"username": "email@cloudops.com"
},
"id": "961a2b96-0a6a-4bb4-9e32-59a3dcc555aa",
"state": "CONFIGURING",
"type": "AVALARA"
},
"taskId": "eea0cf4d-47fc-4f5d-b227-863502486192",
"taskStatus": "PENDING"
}
| Attributes | |
|---|---|
reseller.idUUID |
UUID of the reseller to which the tax provider belongs (AKA an organization id that is a reseller). |
typestring |
The type of tax provider. Possible values are: AVALARA. |
configurationAttributesObject |
The configuration attributes associated to the provider type. This depends on the provider type. |
address.lineOnestring |
The address line 1 of the reseller. |
address.lineTwostring |
The address line 2 of the reseller. |
address.citystring |
The city name of the reseller. |
address.provincestring |
The province of the reseller. |
address.countrystring |
The country of the reseller. |
address.postalCodestring |
The postal code of the reseller. |
createdDatestring |
The date the tax provider was created. |
updatedDatestring |
The last date the tax provider was updated. |
Verify an organization's reseller tax configuration
GET /tax_providers/:id/tax-provider-configured
This endpoint verifies whether or not a given organization's reseller parent organization has configured a tax provider.
# Verify an organization's reseller tax configuration
curl "https://cloudmc_endpoint/api/v2/tax_providers/961a2b96-0a6a-4bb4-9e32-59a3dcc555aa/tax-provider-configured" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
json { "data": true }
| Path Parameters | |
|---|---|
idUUID |
The id of the organization to verify the tax configuration for. |
| Attributes | |
|---|---|
databoolean |
Whether or not the specified organization's reseller parent has a tax provider configured |
Invoice Generation Configuration
Allows you to order different invoicing steps before or after taxes when generating an invoice.
Find the invoice configuration associated to an organization
GET /reseller/settings/invoice-config/find?organizationId=:id
Retrieve the invoice configuration associated to an organization. If the organizationId is omitted, the authenticated user's organization will be used.
# Retrieve the invoice configuration
curl "https://cloudmc_endpoint/api/v2/reseller/settings/invoice-config/find?organizationId=10572c3d-16e5-450f-8af8-a01e50dc52d4" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": {
"organization": {
"id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
},
"id": "d73b5380-cbcc-4b96-9a2e-1448edbf895c",
"steps": [
{
"scope": "ALL_PRODUCTS",
"beforeTax": false,
"type": "CREDIT"
},
{
"scope": "PRODUCTS",
"beforeTax": false,
"type": "CREDIT"
},
{
"scope": "ALL_PRODUCTS",
"beforeTax": true,
"type": "PERCENTAGE"
},
{
"scope": "PRODUCTS",
"beforeTax": true,
"type": "PERCENTAGE"
},
{
"scope": "CATEGORIES",
"beforeTax": true,
"type": "PERCENTAGE"
},
{
"scope": "CATEGORIES",
"beforeTax": true,
"type": "CREDIT"
}
],
"version": 4
}
}
Retrieve the invoice configuration associated to an organization. It returns a default configuration if none is configured for the specified organization.
| Attributes | |
|---|---|
idUUID |
The invoice configuration id. |
organization.idUUID |
The organization id that the invoice configuration is linked to. |
versioninteger |
The invoice configuration version. |
stepsArray[Object] |
The list of invoicing steps. It consists of the cross product between the adjustments type [CREDIT, PERCENTAGE] and their scope [PRODCUTS, CATEGORIES, ALL_PRODUCT] as well as a boolean specifying if this steps needs to be processed before or after taxes when generating an invoice. |
Retrieve invoice configuration
GET /reseller/settings/invoice-config/:id
# Retrieve invoice configuration
curl "https://cloudmc_endpoint/api/v2/reseller/settings/invoice-config/f7ad28a8-1227-44de-9785-6dbd556f3bda" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": {
"organization": {
"id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
},
"id": "d73b5380-cbcc-4b96-9a2e-1448edbf895c",
"steps": [
{
"scope": "ALL_PRODUCTS",
"beforeTax": false,
"type": "CREDIT"
},
{
"scope": "PRODUCTS",
"beforeTax": false,
"type": "CREDIT"
},
{
"scope": "ALL_PRODUCTS",
"beforeTax": true,
"type": "PERCENTAGE"
},
{
"scope": "PRODUCTS",
"beforeTax": true,
"type": "PERCENTAGE"
},
{
"scope": "CATEGORIES",
"beforeTax": true,
"type": "PERCENTAGE"
},
{
"scope": "CATEGORIES",
"beforeTax": true,
"type": "CREDIT"
}
],
"version": 4
}
}
Retrieve the invoice configuration using the provided id.
| Attributes | |
|---|---|
idUUID |
The invoice configuration id. |
organization.idUUID |
The organization id that the invoice configuration is linked to. |
versioninteger |
The invoice configuration version. |
stepsArray[Object] |
The list of invoicing steps. It consists of the cross product between the adjustments type [CREDIT, PERCENTAGE] and their scope [PRODCUTS, CATEGORIES, ALL_PRODUCT] as well as a boolean specifying if this steps needs to be processed before or after taxes when generating an invoice. |
Create invoice configuration
POST /reseller/settings/invoice-config
Create new invoice configuration.
# Creates a new invoice configuration
curl -X POST "https://cloudmc_endpoint/api/v2/reseller/settings/invoice-config" \
-H "MC-Api-Key: your_api_key"
Request body example:
{
"organization": {
"id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
},
"steps": [
{
"scope": "ALL_PRODUCTS",
"beforeTax": false,
"type": "CREDIT"
},
{
"scope": "PRODUCTS",
"beforeTax": false,
"type": "CREDIT"
},
{
"scope": "ALL_PRODUCTS",
"beforeTax": true,
"type": "PERCENTAGE"
},
{
"scope": "PRODUCTS",
"beforeTax": true,
"type": "PERCENTAGE"
},
{
"scope": "CATEGORIES",
"beforeTax": true,
"type": "PERCENTAGE"
},
{
"scope": "CATEGORIES",
"beforeTax": true,
"type": "CREDIT"
}
]
}
The above command returns JSON structured like this:
{
"data": {
"organization": {
"id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
},
"id": "d73b5380-cbcc-4b96-9a2e-1448edbf895c",
"steps": [
{
"scope": "ALL_PRODUCTS",
"beforeTax": false,
"type": "CREDIT"
},
{
"scope": "PRODUCTS",
"beforeTax": false,
"type": "CREDIT"
},
{
"scope": "ALL_PRODUCTS",
"beforeTax": true,
"type": "PERCENTAGE"
},
{
"scope": "PRODUCTS",
"beforeTax": true,
"type": "PERCENTAGE"
},
{
"scope": "CATEGORIES",
"beforeTax": true,
"type": "PERCENTAGE"
},
{
"scope": "CATEGORIES",
"beforeTax": true,
"type": "CREDIT"
}
],
"version": 4
}
}
| Required | |
|---|---|
idUUID |
The invoice configuration id. |
versioninteger |
The invoice configuration version. |
stepsArray[Object] |
The list of invoicing steps. It consists of the cross product between the adjustments type [CREDIT, PERCENTAGE] and their scope [PRODCUTS, CATEGORIES, ALL_PRODUCT] as well as a boolean specifying if this steps needs to be processed before or after taxes when generating an invoice. |
| Optional | |
|---|---|
organization.idUUID |
The organization id the invoice configuration is created for. If not provided, it defaults to the authenticated user's organization |
Update invoice configuration
PUT /reseller/settings/invoice-config/:id
Updates the invoice configuration of an organization.
# Updates an existing invoice configuration for an organization
curl -X PUT "https://cloudmc_endpoint/api/v2/reseller/settings/invoice-config/d73b5380-cbcc-4b96-9a2e-1448edbf895c \
-H "MC-Api-Key: your_api_key"
-H "Content-Type: application/json" \
-d "request-body"
Request body example:
{
"organization": {
"id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
},
"id": "d73b5380-cbcc-4b96-9a2e-1448edbf895c",
"steps": [
{
"scope": "ALL_PRODUCTS",
"beforeTax": false,
"type": "CREDIT"
},
{
"scope": "PRODUCTS",
"beforeTax": false,
"type": "CREDIT"
},
{
"scope": "ALL_PRODUCTS",
"beforeTax": true,
"type": "PERCENTAGE"
},
{
"scope": "PRODUCTS",
"beforeTax": true,
"type": "PERCENTAGE"
},
{
"scope": "CATEGORIES",
"beforeTax": true,
"type": "PERCENTAGE"
},
{
"scope": "CATEGORIES",
"beforeTax": true,
"type": "CREDIT"
}
]
}
The above command returns JSON structured like this:
{
"data": {
"organization": {
"id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
},
"id": "d73b5380-cbcc-4b96-9a2e-1448edbf895c",
"steps": [
{
"scope": "ALL_PRODUCTS",
"beforeTax": false,
"type": "CREDIT"
},
{
"scope": "PRODUCTS",
"beforeTax": false,
"type": "CREDIT"
},
{
"scope": "ALL_PRODUCTS",
"beforeTax": true,
"type": "PERCENTAGE"
},
{
"scope": "PRODUCTS",
"beforeTax": true,
"type": "PERCENTAGE"
},
{
"scope": "CATEGORIES",
"beforeTax": true,
"type": "PERCENTAGE"
},
{
"scope": "CATEGORIES",
"beforeTax": true,
"type": "CREDIT"
}
],
"version": 4
}
}
| Attributes | |
|---|---|
idUUID |
The invoice configuration id. |
organization.idUUID |
The organization id that the invoice configuration is linked to. |
versioninteger |
The invoice configuration version. |
stepsArray[Object] |
The list of invoicing steps. It consists of the cross product between the adjustments type [CREDIT, PERCENTAGE] and their scope [PRODCUTS, CATEGORIES, ALL_PRODUCT] as well as a boolean specifying if this steps needs to be processed before or after taxes when generating an invoice. |
Delete invoice configuration
DELETE /reseller/settings/invoice-config/:id
Delete an existing invoice configuration.
curl -X DELETE "https://cloudmc_endpoint/api/v2/reseller/settings/invoice-config/d785ffcb-9b03-478d-a49b-52a2ccedf1b8" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"taskId": "26022b83-9797-44c0-883c-7e82ecb757e9",
"taskStatus": "SUCCESS"
}
Custom navigation
Custom navigation API allows to customize the navigation per-reseller. Most notably it allows to customize what tabs are shown to a user in the main menu.
List custom navigation
GET /navigation
curl --request GET \
--url http://cloudmc_endpoint/api/v2/navigation/:id \
--header 'Content-Type: application/json' \
--header 'Mc-Api-Key: your_api_key'
The above command returns JSON structured like this:
{
"data": [
{
"reseller": {
"id": "c869e848-6fb3-4850-af3d-42c5666f2c78"
},
"alwaysShowOrgPicker": false,
"id": "f8663571-1d84-4d48-bb86-d4e2a14ea9f9",
"enabled": true
}
]
}
Retrieves a list of custom navigations. Since there is only one custom navigation per reseller this list will either be of length 1 or 0.
| Query Params | |
|---|---|
organization_idUUID |
Return only the custom navigation for the provided organization id. If not provided, will default to the calling user's organization. Must be a reseller organization. |
| Attributes | |
|---|---|
idUUID |
The custom navigations's id. |
reseller.idUUID |
The organization id that the custom field belongs to. |
enabledboolean |
Whether not custom navigation is enabled on the reseller. |
alwaysShowOrgPickerboolean |
Whether or not to always show the organization picker in the sidebar, even when the user has access to only a single organization. |
Get custom navigation
GET /navigation/:id
curl --request GET \
--url http://cloudmc_endpoint/api/v2/navigation/f8663571-1d84-4d48-bb86-d4e2a14ea9f9 \
--header 'Content-Type: application/json' \
--header 'Mc-Api-Key: your_api_key'
The above command returns JSON structured like this:
{
"data": {
"reseller": {
"id": "c869e848-6fb3-4850-af3d-42c5666f2c78"
},
"tabs": [
{
"name": {
"en": "system en",
"fr": "system fr"
},
"rank": 0,
"id": "e4f527bf-9de6-4055-9ede-6949d01156f9",
"tag": {
"en": "tag en",
"fr": "tag fr"
},
"type": "SYSTEM",
"key": "/users"
},
{
"name": {
"en": "system en",
"fr": "sytem fr"
},
"rank": 1,
"id": "125e296a-ae59-4cd7-8d5b-0cf354cbb1cc",
"type": "COMING_SOON"
}
],
"alwaysShowOrgPicker": false,
"id": "f8663571-1d84-4d48-bb86-d4e2a14ea9f9",
"enabled": true
}
}
Retrieves a detailed custom navigation by id.
| Query Params | |
|---|---|
organization_idUUID |
Return only the custom navigation for the provided organization id. If not provided, will default to the calling user's organization. Must be a reseller organization. |
| Attributes | |
|---|---|
idUUID |
The custom navigations's id. |
reseller.idUUID |
The organization id that the custom field belongs to. |
enabledboolean |
Whether not custom navigation is enabled on the reseller. |
alwaysShowOrgPickerboolean |
Whether or not to always show the organization picker in the sidebar, even when the user has access to only a single organization. |
tabsArray[Object] |
List of tabs, the the order they should be displayed in a the menu. |
tabs.nameObject |
Mapped object containing the tab name in different languages. |
tabs.tooltipObject |
Mapped object containing the tab's tooltip name in different languages. |
tabs.tagObject |
Mapped object containing the tab's tag name in different languages. |
tabs.rankint |
The order in which the tab will be displayed in the menu. |
tabs.typeString |
Valid values are SERVICE, SYSTEM and COMING_SOON. |
tabs.iconString |
A string representing a css icon class. |
tabs.serviceConnectionUUID |
The service connection id for a tab of type SERVICE. |
tabs.workspaceString |
The workspace name for a tab of type SERVICE. |
tabs.keyString |
The view key for a tab of type SYSTEM. |
tabs.skipEnvironmentListboolean |
Skip the environment list if there is a single environment associated with the service tab. Configurable for a tab of type SERVICE. |
tabs.showSubTabsboolean |
Whether or not to show the subtabs, as defined by the plugin, underneath the menu tab. Configurable for a tab of type SERVICE. |
tabs.retainEnvironmentboolean |
Retain the selected environment when navigating between tabs with the same service connection. Configurable for a tab of type SERVICE. |
Create custom navigation
POST /navigation
--request POST \
--url http://cloudmc_endpoint/api/v2/navigation \
--header 'Content-Type: application/json' \
--header 'Mc-Api-Key: your_api_key' \
--data '{
"enabled": true,
"reseller": {
"id": "c869e848-6fb3-4850-af3d-42c5666f2c78"
},
"tabs": [
{
"type": "SYSTEM",
"key": "users",
"name": {
"en": "Users",
"fr": "Usagers"
}
},
{
"type": "SERVICE",
"name": {
"en": "Edge compute",
"fr": "Edge compute"
},
"serviceConnection": {
"id": "2d49e70f-e4f8-43e3-b730-92328174214sa21"
},
"workspace": "compute",
"showSubTabs": true,
"skipEnvironmentPicker": true
},
{
"type": "COMING_SOON",
"name": {
"en": "hot new feature",
"fr": "hot new feature fr"
}
}
]
}'
The above command returns JSON structured like this:
{
"data": {
"reseller": {
"id": "c869e848-6fb3-4850-af3d-42c5666f2c78"
},
"tabs": [
{
"name": {
"en": "Users",
"fr": "Usagers"
},
"rank": 0,
"id": "d95a83ed-ba25-432b-94c9-9d59e82f8284",
"type": "SYSTEM",
"key": "users"
},
{
"workspace": "compute",
"name": {
"en": "Edge compute",
"fr": "Edge compute"
},
"icon": "fa fa-server",
"rank": 1,
"skipEnvironmentPicker": true,
"id": "6080bdb2-ceda-4774-aa28-c7f98cd804a4",
"showSubTabs": true,
"type": "SERVICE",
"serviceConnection": {
"id": "2d49e70f-e4f8-43e3-b730-92328174214sa21"
}
},
{
"name": {
"en": "hot new feature",
"fr": "hot new feature fr"
},
"rank": 2,
"id": "cb36c538-6f6b-47af-bfa8-daad56ce58ed",
"type": "COMING_SOON"
}
],
"alwaysShowOrgPicker": false,
"id": "e80adf4d-5401-4cff-b393-93a7f10f4d71",
"enabled": true
}
}
| Optional | |
|---|---|
reseller.idUUID |
The organization id that the custom field belongs to. If not provided defaults to caller's organization. |
enabledboolean |
Whether not custom navigation is enabled on the reseller. Defaults to false. |
alwaysShowOrgPickerboolean |
Whether or not to always show the organization picker in the sidebar, even when the user has access to only a single organization. Defaults to false. |
tabsArray[Object] |
List of tabs, in the order they should be displayed in the menu. |
tabs.typeObject |
Required in tab object. Valid values are SERVICE, SYSTEM and COMING_SOON. |
tabs.nameObject |
Required in tab object. Mapped object containing the tab name in different languages. Need to specify all languages for target reseller's branding. |
tabs.tooltipObject |
Mapped object containing the tab's tooltip name in different languages. Need to specify all languages for target reseller's branding. |
tabs.tagObject |
Mapped object containing the tab's tag name in different languages. Need to specify all languages for target reseller's branding. |
tabs.iconString |
A string representing a css icon class. |
tabs.serviceConnectionUUID |
Required if type SERVICE. The service connection id for a tab of type SERVICE. |
tabs.workspaceString |
Required if type SERVICE. The workspace name for a tab of type SERVICE. |
tabs.keyString |
Required if type SYSTEM. The view key for a tab of type SYSTEM. |
tabs.skipEnvironmentListboolean |
Skip the environment list if there is a single environment associated with the service tab. Configurable for a tab of type SERVICE. |
tabs.showSubTabsboolean |
Whether or not to show the subtabs, as defined by the plugin, underneath the menu tab. Configurable for a tab of type SERVICE. |
tabs.retainEnvironmentboolean |
Retain the selected environment when navigating between tabs with the same service connection. Configurable for a tab of type SERVICE. |
Update custom navigation
PUT /navigation/:id
curl --request PUT \
--url http://cloudmc_endpoint/api/v2/navigation/e80adf4d-5401-4cff-b393-93a7f10f4d71 \
--header 'Content-Type: application/json' \
--header 'Mc-Api-Key: your_api_key' \
--data '{
"id": "e80adf4d-5401-4cff-b393-93a7f10f4d71",
"reseller": {
"id": "c869e848-6fb3-4850-af3d-42c5666f2c78"
},
"enabled": false,
"tabs": []
}'
The above command returns JSON structured like this:
{
"data": {
"reseller": {
"id": "c869e848-6fb3-4850-af3d-42c5666f2c78"
},
"tabs": [],
"alwaysShowOrgPicker": false,
"id": "e80adf4d-5401-4cff-b393-93a7f10f4d71",
"enabled": false
}
}
Update a custom navigation.
| Required | |
|---|---|
idUUID |
The id of the custom navigation. Cannot be changed. |
reseller.idUUID |
The organization id that the custom field belongs to. If not provided defaults to caller's organization. |
| Optional | |
|---|---|
enabledboolean |
Whether not custom navigation is enabled on the reseller. Defaults to false. |
alwaysShowOrgPickerboolean |
Whether or not to always show the organization picker in the sidebar, even when the user has access to only a single organization. Defaults to false. |
tabsArray[Object] |
List of tabs, in the order they should be displayed in a the menu. Replaces all tabs currently set on the object. |
tabs.typeObject |
Required in tab object. Valid values are SERVICE, SYSTEM and COMING_SOON. |
tabs.nameObject |
Required in tab object. Mapped object containing the tab name in different languages. Need to specify all languages for target reseller's branding. |
tabs.tooltipObject |
Mapped object containing the tab's tooltip name in different languages. Need to specify all languages for target reseller's branding. |
tabs.tagObject |
Mapped object containing the tab's tag name in different languages. Need to specify all languages for target reseller's branding. |
tabs.iconString |
A string representing a css icon class. |
tabs.serviceConnectionUUID |
Required if type SERVICE. The service connection id for a tab of type SERVICE. |
tabs.workspaceString |
Required if type SERVICE. The workspace name for a tab of type SERVICE. |
tabs.keyString |
Required if type SYSTEM. The view key for a tab of type SYSTEM. |
tabs.skipEnvironmentListboolean |
Skip the environment list if there is a single environment associated with the service tab. Configurable for a tab of type SERVICE. |
tabs.showSubTabsboolean |
Whether or not to show the subtabs, as defined by the plugin, underneath the menu tab. Configurable for a tab of type SERVICE. |
tabs.retainEnvironmentboolean |
Retain the selected environment when navigating between tabs with the same service connection. Configurable for a tab of type SERVICE. |
Delete custom navigation
DELETE /navigation/:id
curl --request DELETE \
--url http://cloudmc_endpoint/api/v2/navigation/e80adf4d-5401-4cff-b393-93a7f10f4d71 \
--header 'Mc-Api-Key: you_api_key'
The above command returns JSON structured like this:
{
"taskId": "96bb7528-dc19-48b5-b713-9e55c7664aaf",
"taskStatus": "SUCCESS"
}
Delete's a custom navigation configuration.
Metrics
The metrics API can be queried to obtain metrics data that is pushed by the service to CloudMC metric data store.
Retrieve Metrics for a Specified Interval
GET /metrics/{serviceCode}/{metricId}
Retrieves metrics for a given metric id in a specified interval
# Retrieve metrics for a given interval
curl "https://cloudmc_endpoint/api/v2/metrics/stackpath-cox-dev/ingress_bandwidth?startDate=2021-08-12T10:50:46.386Z&endDate=2021-08-15T10:50:46.386Z&size=12&unit=hours&entityId=1923471a-6a72-474d-9e19-63075bc1020b" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"data": {
"ingress_bandwidth": [
{
"entityId": "1923471a-6a72-474d-9e19-63075bc1020b",
"label": "2021-08-12T12:00:00.000",
"value": 0.27
},
{
"entityId": "1923471a-6a72-474d-9e19-63075bc1020b",
"label": "2021-08-13T00:00:00.000",
"value": 0.29
},
{
"entityId": "1923471a-6a72-474d-9e19-63075bc1020b",
"label": "2021-08-13T12:00:00.000",
"value": 0.25
},
{
"entityId": "1923471a-6a72-474d-9e19-63075bc1020b",
"label": "2021-08-14T00:00:00.000",
"value": 0.37
},
{
"entityId": "1923471a-6a72-474d-9e19-63075bc1020b",
"label": "2021-08-14T12:00:00.000",
"value": 0.26
},
{
"entityId": "1923471a-6a72-474d-9e19-63075bc1020b",
"label": "2021-08-15T00:00:00.000",
"value": 0.21
}
]
}
}
| Path Parameters | |
|---|---|
serviceCodestring |
A globally unique code that identifies this service connection.. |
metricIdstring |
A unique identifier used to define a MetricDescriptor. |
| Required Query Parameters | |
|---|---|
startDateDate |
The start date of the interval to query metrics for. The date must be in a valid ISO-8601 format. The start date must be provided to query this endpoint. |
endDateDate |
The start date of the interval to query metrics for. The date must be in a valid ISO-8601 format. The end date must be provided to query this endpoint. |
| Optional Query Parameters | |
|---|---|
environmentstring |
The name of the environment to query metrics for. |
aggregationTypestring |
How the queried metrics should be aggregated. The possible values are sum, count, min, max, avg (average). When not provided, the default value used is average. |
sizeinteger |
The size of the data points granularity in the response. The size must be a positive integer value. When combined with unit, this forms an expression similar to 1 hour, or 1 day, etc. The default value used is 5. |
unitstring |
The unit of the data points granularity in the response. The unit must be a valid Java Chronounit. The default value is MINUTES. |
entityTypeString |
The type of entity to query metrics for. When provided, only those metric records that have the provided entityType are aggregated. |
entityIdUUID |
The id of the entity to query metrics for. When provided, only those metric records that have the provided entityId are aggregated. |
| Attributes | |
|---|---|
labelUUID |
The UTC timestamp used to label the value returned by the query. |
valueNumber |
The value of the metric at the given timestamp. |
entityIdUUID |
The id of the entity metrics data was queried for. |
Caches
Whenever any entity objects is retrieved from the backend-service, the result of the fetch operation will be automatically cached temporarily to avoid any subsequent calls to the backend service.
This behaviour can be enabled/disabled per Service Connection by browsing to the Service Connection page under the Administration menu.
Clear the Fetcher Cache
This operation will clear the current content of the cache containing entity objects retrieved from the backend-service by the Fetcher.
DELETE /cache/fetcher
curl -X DELETE \
"https://cloudmc_endpoint/rest/cache/fetcher?connectionId=f789261c-b2db-427e-bdff-dd3629192087&environmentId=099a86b2-0998-4d99-b036-0d85fa7c82a7" \
-h "Mc-Api-Key: your_api_key"
The above command returns no content (HTTP 204 No Content)
Clear the cache for the given environment within the given connection.
| Query Params | |
|---|---|
connectionIdUUID |
The Connection ID |
environmentIdUUID |
The Environment ID |
Custom UI Settings
Find custom UI settings associated to an organization
GET /reseller/settings/custom_ui/find?organizationId=:id
Retrieve the custom UI settings associated to an organization. If the organizationId is omitted, the authenticated user's organization will be used.
# Retrieve the custom UI settings
curl "https://cloudmc_endpoint/api/v2/reseller/settings/custom_ui/find?organizationId=10572c3d-16e5-450f-8af8-a01e50dc52d4" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": {
"organization": {
"id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
},
"id": "d785ffcb-9b03-478d-a49b-52a2ccedf1b8",
"version": 1,
"enabled": true,
"customUIRootUrl": "https://newui.example.com",
"domainToken": "example.com",
"applyTags": [],
"denyTags": [],
"redirectRoles": []
}
}
Retrieve the custom UI settings associated to an organization.
| Attributes | |
|---|---|
idUUID |
The configured custom UI settings' id. |
organization.idUUID |
The organization id that the custom UI settings are linked to. It cannot be changed. |
versioninteger |
The custom UI settings version. |
enabledboolean |
If the custom UI redirection is enabled or not. |
customUIRootUrlstring |
The base root that the user will be redirected to once the user is logged in. |
domainTokenstring |
The domain name that will be used in the authentication cookie. The cookie must be acceptable by both the reseller organization custom domain and the url provided in this configuration. |
applyTagsArray[string] |
The list of organization tags that will redirect the user of sub-organizations to the custom UI if they match. |
denyTagsArray[string] |
The list of organization tags that will not redirect the user of sub-organizations to the custom UI if they match. |
redirectRolesArray[string] |
The list of roles that users of the reseller will be redirected to the new UI. Possible values are reseller,admin,user,guest. |
Retrieve custom UI settings
GET /reseller/settings/custom_ui/:id
# Retrieve custom UI settings
curl "https://cloudmc_endpoint/api/v2/reseller/settings/custom_ui/d785ffcb-9b03-478d-a49b-52a2ccedf1b8" \
-H "MC-Api-Key: your_api_key"
The above command returns JSON structured like this:
{
"data": {
"organization": {
"id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
},
"id": "d785ffcb-9b03-478d-a49b-52a2ccedf1b8",
"version": 1,
"enabled": true,
"customUIRootUrl": "https://newui.example.com",
"domainToken": "example.com",
"applyTags": [],
"denyTags": [],
"redirectRoles": []
}
}
Retrieve the custom UI settings associated to the custom UI settings id.
| Attributes | |
|---|---|
idUUID |
The configured custom UI settings' id. |
organization.idUUID |
The organization id that the custom UI settings are linked to. It cannot be changed. |
versioninteger |
The custom UI settings version. |
enabledboolean |
If the custom UI redirection is enabled or not. |
customUIRootUrlstring |
The base root that the user will be redirected to once the user is logged in. |
domainTokenstring |
The domain name that will be used in the authentication cookie. The cookie must be acceptable by both the reseller organization custom domain and the url provided in this configuration. |
applyTagsArray[string] |
The list of organization tags that will redirect the user of sub-organizations to the custom UI if they match. |
denyTagsArray[string] |
The list of organization tags that will not redirect the user of sub-organizations to the custom UI if they match. |
redirectRolesArray[string] |
The list of roles that users of the reseller will be redirected to the new UI. Possible values are reseller,admin,user,guest. |
Create custom UI settings
POST /reseller/settings/custom_ui
Create new custom UI settings.
# Creates a new custom UI settings
curl -X POST "https://cloudmc_endpoint/api/v2/reseller/settings/custom_ui" \
-H "MC-Api-Key: your_api_key"
Request body example:
{
"organization": {
"id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
},
"enabled": true,
"customUIRootUrl": "https://newui.example.com",
"domainToken": "example.com",
"applyTags": [],
"denyTags": [],
"redirectRoles": []
}
The above command returns JSON structured like this:
{
"data": {
"organization": {
"id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
},
"id": "d785ffcb-9b03-478d-a49b-52a2ccedf1b8",
"version": 1,
"enabled": true,
"customUIRootUrl": "https://newui.example.com",
"domainToken": "example.com",
"applyTags": [],
"denyTags": [],
"redirectRoles": []
}
}
| Required | |
|---|---|
enabledboolean |
If the custom UI redirection is enabled or not. |
| Optional | |
|---|---|
organization.idUUID |
The organization id that the custom UI settings are linked to. If the organizationId is omitted, the authenticated user's organization will be used. |
customUIRootUrlstring |
The base root that the user will be redirected to once the user is logged in. Required if the custom UI is enabled. |
domainTokenstring |
The domain name that will be used in the authentication cookie. The cookie must be acceptable by both the reseller organization custom domain and the url provided in this configuration. Required if the custom UI is enabled. |
applyTagsArray[string] |
The list of organization tags that will redirect the user of sub-organizations to the custom UI if they match. |
denyTagsArray[string] |
The list of organization tags that will not redirect the user of sub-organizations to the custom UI if they match. |
redirectRolesArray[string] |
The list of roles that users of the reseller will be redirected to the new UI. Possible values are reseller,admin,user,guest. |
Update custom UI settings
PUT /reseller/settings/custom_ui/:id
Updates the custom UI settings of an organization.
# Updates an existing custom UI settings for an organization
curl -X PUT "https://cloudmc_endpoint/api/v2/reseller/settings/custom_ui/d785ffcb-9b03-478d-a49b-52a2ccedf1b8 \
-H "MC-Api-Key: your_api_key"
-H "Content-Type: application/json" \
-d "request-body"
Request body example:
{
"organization": {
"id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
},
"id": "d785ffcb-9b03-478d-a49b-52a2ccedf1b8",
"version": 1,
"enabled": true,
"customUIRootUrl": "https://newui.example.com",
"domainToken": "example.com",
"applyTags": [],
"denyTags": [],
"redirectRoles": []
}
The above command returns JSON structured like this:
{
"data": {
"organization": {
"id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
},
"id": "d785ffcb-9b03-478d-a49b-52a2ccedf1b8",
"version": 1,
"enabled": true,
"customUIRootUrl": "https://newui.example.com",
"domainToken": "example.com",
"applyTags": [],
"denyTags": [],
"redirectRoles": []
}
}
| Required | |
|---|---|
idUUID |
The configured custom UI settings' id. |
organization.idUUID |
The organization id that the custom UI settings are linked to. It cannot be changed. |
enabledboolean |
If the custom UI redirection is enabled or not. |
| Optional | |
|---|---|
customUIRootUrlstring |
The base root that the user will be redirected to once the user is logged in. Required if the custom UI is enabled. |
domainTokenstring |
The domain name that will be used in the authentication cookie. The cookie must be acceptable by both the reseller organization custom domain and the url provided in this configuration. Required if the custom UI is enabled. |
applyTagsArray[string] |
The list of organization tags that will redirect the user of sub-organizations to the custom UI if they match. |
denyTagsArray[string] |
The list of organization tags that will not redirect the user of sub-organizations to the custom UI if they match. |
redirectRolesArray[string] |
The list of roles that users of the reseller will be redirected to the new UI. Possible values are reseller,admin,user,guest. |
Delete custom UI settings
DELETE /reseller/settings/custom_ui/:id
Delete an existing custom UI settings.
curl -X DELETE "https://cloudmc_endpoint/api/v2/reseller/settings/custom_ui/d785ffcb-9b03-478d-a49b-52a2ccedf1b8" \
-H "MC-Api-Key: your_api_key"
The above command returns a JSON structured like this:
{
"taskId": "26022b83-9797-44c0-883c-7e82ecb757e9",
"taskStatus": "SUCCESS"
}
CloudStack plugin
The CloudStack plugin provides endpoints for carrying out operations on CloudMC compute and networking entities. While each operation has its own validation and required fields, all operations need to specify the service code and environment in which they should be carried out. The following example URL describes how to specify this information for all entities.
https://cloudmc_endpoint/api/v2/services/:service_code/:environment_name/:entity_type
Compute
Instances
Deploy and manage your instances.
For information regarding bare metal instances, please see bare metal instances.
List instances
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/instances"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "9db8ff2f-b49b-466d-a2f3-c1e6def408f4",
"name": "my_instance",
"affinityGroupIds": [],
"computeOfferingId": "3caab5ed-b5a2-4d8a-82e4-51c46168ee6c",
"computeOfferingName": "1vCPU.512MB",
"cpuCount": 1,
"hostname": "my_instance",
"imageId": "5f968ad6-56d0-4d0d-ad7e-f8f4a5b5d986",
"imageName": "CentOS 6.8 PV",
"ipAddress": "10.164.212.68",
"isPasswordEnabled": true,
"macAddress": "02:00:2b:67:00:30",
"memoryInMB": 512,
"networkId": "d5a68379-a9ee-404f-9492-a1964b374d6f",
"networkName": "Web-test_area",
"state": "Running",
"username": "cca-user",
"vpcId": "9eb1592c-f92f-4ddd-9799-b58caf896328",
"vpcName": "prod-VPC",
"zoneId": "04afdbd1-e32d-4999-86d0-96703736dded",
"zoneName": "QC-1"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/instances
Retrieve a list of all instances in a given environment.
| Attributes | |
|---|---|
idUUID |
The id of the instance |
namestring |
The display name of the instance |
affinityGroupIdsArray[UUID] |
The id(s) of the affinity groups to which the instance is associated. |
computeOfferingIdUUID |
The compute offering id of the instance |
computeOfferingNamestring |
The compute offering name of the instance |
cpuCountint |
The number of vCPUs associated with the instance's compute offering |
hostnamestring |
The host name of the instance |
imageIdUUID |
The image id of the instance |
imageNamestring |
The image name of the instance |
ipAddressstring |
The instance's private IPv4 address |
isPasswordEnabledboolean |
Indicate whether a password can be used for remote connections |
macAddressstring |
The instance's MAC address |
memoryInMBint |
The number of megabytes associated with the instance's compute offering |
networkIdUUID |
The id of the network where instance is deployed |
networkNamestring |
The name of the network where instance is deployed |
statestring |
The current state of the instance |
usernamestring |
The username that can be used to connect to the instance |
vpcIdUUID |
The id of the associated VPC |
vpcNamestring |
The name of associated VPC |
zoneIdUUID |
The id of the zone where instance is deployed |
zoneNamestring |
The name of associated zone |
Retrieve an instance
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/instances/5951c2b8-e901-4c01-8ae0-cb8d7c508d29"
The above command returns a JSON structured like this:
{
"data": {
"id": "9db8ff2f-b49b-466d-a2f3-c1e6def408f4",
"name": "backup_instance",
"affinityGroupIds": [],
"computeOfferingId": "3caab5ed-b5a2-4d8a-82e4-51c46168ee6c",
"computeOfferingName": "1vCPU.512MB",
"cpuCount": 1,
"hostname": "backup_instance",
"imageId": "5f968ad6-56d0-4d0d-ad7e-f8f4a5b5d986",
"imageName": "CentOS 6.8 PV",
"ipAddress": "10.164.212.68",
"isPasswordEnabled": true,
"macAddress": "02:00:2b:67:00:30",
"memoryInMB": 512,
"networkId": "d5a68379-a9ee-404f-9492-a1964b374d6f",
"networkName": "Web-test_area",
"state": "Running",
"userData": "",
"username": "cca-user",
"vpcId": "9eb1592c-f92f-4ddd-9799-b58caf896328",
"vpcName": "prod-VPC",
"zoneId": "04afdbd1-e32d-4999-86d0-96703736dded",
"zoneName": "QC-1",
"publicIps": [{
"id": "7a204b7f-1039-4867-8971-c1e4f778ef33",
"ipAddress": "199.215.226.46",
"purposes": [
"PORT_FORWARDING"
],
"ports": [
"22"
]
}],
"nics": [{
"id": "f401d989-b149-4870-99f3-1991fec31454",
"isDefault": true,
"networkId": "d5a68379-a9ee-404f-9492-a1964b374d6f"
}]
}
}
GET /services/:service_code/:environment_name/instances/:id
Retrieve information about a specific instance.
| Attributes | |
|---|---|
idUUID |
The id of the instance |
namestring |
The display name of the instance |
affinityGroupIdsArray[UUID] |
The id(s) of the affinity groups to which the instance is associated. |
computeOfferingIdUUID |
The compute offering id of the instance |
computeOfferingNamestring |
The compute offering name of the instance |
cpuCountint |
The number of vCPUs associated with the instance's compute offering |
hostnamestring |
The host name of the instance |
imageIdUUID |
The image id of the instance |
imageNamestring |
The image name of the instance |
ipAddressstring |
The instance's private IPv4 address |
isPasswordEnabledboolean |
Indicate whether a password can be used for remote connections |
macAddressstring |
The instance's MAC address |
memoryInMBint |
The number of megabytes associated with the instance's compute offering |
networkIdUUID |
The id of the network where instance is deployed |
networkNamestring |
The name of the network where instance is deployed |
nicsArray[NIC] |
The NICs of the instance includes: id, isDefault, networkId |
publicIpsArray[PublicIp] |
The public IP addresses associated to the instance includes: id, purposes, ipAddress, ports |
statestring |
The current state of the instance |
userDatastring |
The user data of the instance |
usernamestring |
The username that can be used to connect to the instance |
vpcIdUUID |
The id of the associated VPC |
vpcNamestring |
The name of associated VPC |
zoneIdUUID |
The id of the zone where instance is deployed |
zoneNamestring |
The name of associated zone |
Create an instance
# Here is the absolute minimum information required to create a new instance:
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/instances"
Request body example:
{
"name": "jarvis",
"additionalDiskIops": 1000,
"additionalDiskSizeInGb": 20,
"affinityGroupId": "1c0bfd2b-d609-4892-a43e-273654532d26",
"computeOfferingId": "3caab5ed-b5a2-4d8a-82e4-51c46168ee6c",
"diskOfferingId": "f16f7f1b-462d-47b9-97bb-25a19e47a648",
"networkId": "55ccea7f-8286-479e-a648-dd4a45866daf",
"portsToForward": ["80", "9999"],
"rootVolumeSizeInGb": 60,
"sshKeyName": "mysshkey",
"templateId": "5f968ad6-56d0-4d0d-ad7e-f8f4a5b5d986",
"userData": "#!/bin/bash\necho 'hello world'",
"volumeIdToAttach": "2478012b-3cf3-4eef-a8d6-85eb8599df6d"
}
POST /services/:service_code/:environment_name/instances
Create an instance in an environment. This endpoint allows you to easily attach a new or existing data volume and add port forwarding rules to the new instance without doing additional API calls.
In order to create bare metal instances, please see the acquire operation.
| Required | |
|---|---|
namestring |
Name of the newly created instance |
computeOfferingIdUUID |
The compute offering will determine the number of CPU and RAM of your instance |
networkIdUUID |
The network in which the instance will be created. If you don't have a network, it can be created through the create network api. |
templateIdUUID |
The template to use for this instance |
| Optional | |
|---|---|
additionalDiskIopsint |
The number of IOPS the additional disk should have. You must choose a disk offering with custom IOPS enabled. |
additionalDiskSizeInGbint |
The number of GB the additional disk should have. You must choose a disk offering with custom disk size enabled. |
affinityGroupIdUUID |
The affinity group where to create the instance. |
cpuCountint |
If the compute offering requires custom values (i.e. "custom": true), this value must be provided. |
diskOfferingIdUUID |
The disk offering to be used for a new volume to attach to this instance |
ipAddressstring |
Private IPv4 address of this instance, must be within network's CIDR and not collide with other instances on the network. |
memoryInMBint |
If the compute offering requires custom values (i.e. "custom": true), this value must be provided. |
portsToForwardarray[string] |
The ports you would like to open on the instance. It will try to use an existing public IP address, if it can't find one it will acquire a new public IP. |
publicKeystring |
The public key to use for this instance. |
rootVolumeSizeInGbint |
The number of GB of the root volume. You must choose a template that allows the resize of root volume. If none specified, then the default one of the template will be used. |
sshKeyNamestring |
The name of the SSH key to use for this instance. If you don't have an SSH key registered, you can do so through this api. |
userDatastring |
User data is data that can be accessed and interpreted in the instance. |
volumeIdToAttachUUID |
The volume to attach to this instance. |
Update an instance
# Here is the absolute minimum information required to create a new instance:
curl -X PUT \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/instances/5951c2b8-e901-4c01-8ae0-cb8d7c508d29"
Request body example:
{
"name": "hal",
"hostname": "hal_9000"
}
POST /services/:service_code/:environment_name/instances/:id
Update the name and hostname of an existing instance.
| Optional | |
|---|---|
namestring |
Updated name of instance |
hostnamestring |
Updated hostname of instance. |
Destroy an instance
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint:443/v1/services/compute-on/test_area/instances/5bf7352c-eed2-43dc-83f1-89917fb893ca"
Request body example:
{
"deleteSnapshots":true,
"purgeImmediately":true,
"publicIpIdsToRelease":[
"fe446d61-a22c-403a-87bf-5351e65dc54d"
],
"volumeIdsToDelete":[
"e3d4045d-3ef7-464d-92a3-fc18269f36e2"
]
}
DELETE /services/:service_code/:environment_name/instances/:id
Destroys an existing instance. The instance needs to be in the Running, Stopped or Error state for the operation to work. This endpoint allows you to do additional cleanup of resources attached to this instance such as public IPs, volumes and snapshots. If the purgeImmediately flag is not true, then it will not completely remove the instance from the environment. (i.e. the instance could still be recovered).
In order to destory bare metal instances, please see the release operation.
| Optional | |
|---|---|
deleteSnapshotsboolean |
Will delete all snapshots of volumes attached to this instance if true, will keep snapshots otherwise. |
publicIpIdsToReleaseArray[UUID] |
List of IDs of the public IP addresses to release with the instance. Can only release public IPs of the instance being destroyed and they must not be used by other instances. |
purgeImmediatelyboolean |
Will destroy and purge the instance if true, puts the instance in destroyed state otherwise. An instance that wasn't purged can be recovered. |
volumeIdsToDeleteArray[UUID] |
List of IDs of the data volumes to delete with the instance. Can only destroy data volumes that are attached to this instance. |
Start an instance
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/instances/5951c2b8-e901-4c01-8ae0-cb8d7c508d29?operation=start"
POST /services/:service_code/:environment_name/instances/:id?operation=start
Start an existing instance. The instance must be in the Stopped state for this operation to work.
Stop an instance
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/instances/5951c2b8-e901-4c01-8ae0-cb8d7c508d29?operation=stop"
Request body example:
{
"forceStop":true
}
POST /services/:service_code/:environment_name/instances/:id?operation=stop
Stop an existing instance. The instance must be in either the Running or Stopping state for this operation to work. The default behavior is that the instance (denote by id) will be stopped gracefully. An additional parameter can be passed with the call to force stop an instance. If the API is invoked on an instance that is already in the Stopping state, then a force stop is enforced regardless of whether this optional parameter was provided or not.
| Optional | |
|---|---|
forceStopboolean |
Setting it to true will force stop an instance that is either Running or in the process of Stopping |
Reboot an instance
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/instances/5951c2b8-e901-4c01-8ae0-cb8d7c508d29?operation=reboot"
POST /services/:service_code/:environment_name/instances/:id?operation=reboot
Reboot an existing instance. The instance must be in the Running or Stopped state for this operation to work.
Purge an instance
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/instances/5951c2b8-e901-4c01-8ae0-cb8d7c508d29?operation=purge"
POST /services/:service_code/:environment_name/instances/:id?operation=purge
Purges an existing instance (i.e. completely remove it from the environment). The instance must be in a Destroyed state.
Recover an instance
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/instances/5951c2b8-e901-4c01-8ae0-cb8d7c508d29?operation=recover"
POST /services/:service_code/:environment_name/instances/:id?operation=recover
Recover an existing instance that was previously destroyed. The instance must be in a Destroyed state.
Change the compute offering of an instance
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/instances/5951c2b8-e901-4c01-8ae0-cb8d7c508d29?operation=changeComputeOffering"
POST /services/:service_code/:environment_name/instances/:id?operation=changeComputeOffering
Change the compute offering of an existing instance.
| Required | |
|---|---|
computeOfferingIdUUID |
Id of the new compute offering for the instnace |
| Required | (if custom compute offering) |
|---|---|
cpuCountinteger |
Number of CPUs for the instance |
memoryInMBinteger |
Amount of memory in MB for the instance |
Reset the password of an instance
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/instances/5951c2b8-e901-4c01-8ae0-cb8d7c508d29?operation=resetPassword"
POST /services/:service_code/:environment_name/instances/:id?operation=resetPassword
Reset the password of the default user of an existing instance. The new password of the instance will be in the task result.
Change network of an instance
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/instances/5951c2b8-e901-4c01-8ae0-cb8d7c508d29?operation=changeNetwork"
POST /services/:service_code/:environment_name/instances/:id?operation=changeNetwork
Move an instance to another network. NOTE: This will destroy all port forwarding rules associated to this instance and remove the instance from all load balancing rules. Additionally, it will reboot your instance.
| Required | |
|---|---|
networkIdUUID |
The destination network. |
Associate an SSH key to an instance
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/instances/5951c2b8-e901-4c01-8ae0-cb8d7c508d29?operation=associateSSHKey"
Request body example:
{
"sshKeyName": "my_ssh_key"
}
POST /services/:service_code/:environment_name/instances/:id?operation=associateSSHKey
Associate a new SSH key to the default user of an existing instance. This will override any other SSH key associated to the instance for the default user. You can register a new SSH key with the register SSH key endpoint.
| Required | |
|---|---|
sshKeyNamestring |
The name of the SSH key to associate to the instance |
Attach an ISO to an instance
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/testing/instances/5951c2b8-e901-4c01-8ae0-cb8d7c508d29?operation=attachIso"
Request body example:
{
"isoId": "f092a051-8b3f-4941-b47f-5ecb77f3423b"
}
POST /services/:service_code/:environment_name/instances/:id?operation=attachIso
Attach an existing, non-bootable ISO to an instance. Each instance may have only one ISO attached at a time.
| Required | |
|---|---|
isoIdUUID |
The id of the ISO to attach |
Detach the ISO from an instance
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/testing/instances/e922e5fc-8fee-4688-ad93-c9ef5d7eb685?operation=detachIso"
# No parameters required
POST /services/:service_code/:environment_name/instances/:id?operation=detachIso
Detach the currently attached ISO from an instance.
Bare metal instances
Deploy and manage your bare metal instances.
For information regarding virtual instances, please see instances.
List bare metal instances
Identical to virtual instances, please see list instances.
Retrieve a bare metal instance
Identical to virtual instances, please see retrieve an instance.
Acquire a bare metal instance
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/instances"
Request body example:
{
"name": "jarvis",
"computeOfferingId": "3caab5ed-b5a2-4d8a-82e4-51c46168ee6c",
"networkId": "55ccea7f-8286-479e-a648-dd4a45866daf",
"portsToForward": ["80", "9999"],
"sshKeyName": "mysshkey",
"templateId": "5f968ad6-56d0-4d0d-ad7e-f8f4a5b5d986",
"userData": "#!/bin/bash\necho 'hello world'"
}
POST /services/:service_code/:environment_name/instances?operation=acquireBareMetal
Acquire a bare metal instance in an environment. This endpoint allows you to easily add port forwarding rules and user data to the instance without doing additional API calls. This operation is analogous to the create an instance operation for virtual instances.
| Required | |
|---|---|
namestring |
Name of the newly created instance |
computeOfferingIdUUID |
The compute offering will determine the hardware specifications of your instance. |
networkIdUUID |
The network in which the instance will be created. If you don't have a network, it can be created through the create network api. |
sshKeyNamestring |
The name of the SSH key to use for this instance. If you don't have an SSH key registered, you can do so through this api. |
templateIdUUID |
The template to use for this instance. |
| Optional | |
|---|---|
ipAddressstring |
Private IPv4 address of this instance, must be within network's CIDR and not collide with other instances on the network. |
portsToForwardarray[string] |
The ports you would like to open on the instance. It will try to use an existing public IP address, if it can't find one it will acquire a new public IP. |
userDatastring |
User data is data that can be accessed and interpreted in the instance. |
Release a bare metal instance
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/instances/5951c2b8-e901-4c01-8ae0-cb8d7c508d29?operation=releaseBareMetal"
Request body example:
{
"publicIpIdsToRelease":[
"fe446d61-a22c-403a-87bf-5351e65dc54d"
]
}
POST /services/:service_code/:environment_name/instances/:id?operation=releaseBareMetal
Release an acquired bare metal instance from the environment. The instance will be immediatedly released. This operation is analogous to the destroy an instance operation with the purgeImmediately flag set to true (i.e. the instance will not be recovered).
Associate an SSH key to an instance
Identical to virtual instances, please see associate an SSH key.
Templates
A template is a virtual disk image that can be used on the creation of an instance. It contains the operating system which can contain some predefined configuration, files and software.
List templates
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/templates"
The above command returns a JSON structured like this:
{
"data": [{
"id": "0b3fea04-b1ed-48cf-921d-96795dfe9a81",
"name": "ubuntu",
"description": "Example template",
"defaultUsername": "cmc-user",
"size": 52428800,
"availablePublicly": false,
"ready": true,
"dynamicallyScalable": true,
"extractable": false,
"sshKeyEnabled": true,
"created":"2016-10-24 2:40:29 PM EDT",
"zoneId":"ea901007-056b-4c50-bb3a-2dd635fce2ab",
"zoneName": "zone1",
"osTypeId":"d38dc1d9-dd34-4fdd-8f51-a973f8fe5f3b",
"osTypeName": "Other (64-bit)",
"availableInZones": [
"ea901007-056b-4c50-bb3a-2dd635fce2ab"
],
"hypervisor": "VMware",
"format": "OVA",
"nicAdapter": "e1000",
"rootDiskController": "scsi",
"keyboard": "uk"
}],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/templates
Retrieve a list of all templates of an environment It will include all the public templates of the system.
| Attributes | |
|---|---|
idUUID |
The id of the template |
namestring |
The name of the template |
descriptionstring |
The description of the template |
defaultUsernamestring |
The default username of the template |
sizelong |
The size of the template in bytes |
availablePubliclyboolean |
true if public to everyone. Your custom templates will always be private |
readyboolean |
true if the template is ready to be used for a new instance |
dynamicallyScalableboolean |
true if you can dynamically scale an instance with this template |
extractableboolean |
true if you want the template to be downloadable from a generated URL |
createdstring |
The creation date of the template |
osTypeIdUUID |
Id of the OS type |
osTypeNamestring |
The OS type of the template (e.g. Ubuntu, CentOS...) |
sshEnabledboolean |
false if you want to enable sshKey for the template |
zoneIdUUID |
The zone id that the template is available in. Empty if available in multiple zones |
zoneNamestring |
The zone id that the template is available in. Empty if available in multiple zones |
availableInZonesarray[UUID] |
List of all zone ids that the template is available in |
hypervisorstring |
The name of the hypervisor |
formatstring |
The template format for the chosen hypervisor |
nicAdapterstring |
VMWare only The network interface controller name. Empty if not selected.Values: e1000, pcnet32, vmxnet2 or vmxnet3. |
rootDiskControllerstring |
VMWare only The root disk controller name. Empty if not selected.Values: ide, scsi for CloudStack version up to 4.4. Values: ide, scsi, osdefault, pvscsi, lsilogic, lsisas1068, buslogic for CloudStack version 4.5 and up. |
keyboardstring |
VMWare only The keyboard type name. Empty if not selected.Values: us, uk, jp, sc. |
Retrieve a template
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/templates/162cdfcb-45e5-4aa6-81c4-124c94621bdb"
The above command returns a JSON structured like this:
{
"data": {
"id": "0b3fea04-b1ed-48cf-921d-96795dfe9a81",
"name": "ubuntu",
"description": "Example template",
"defaultUsername": "cmc-user",
"size": 52428800,
"availablePublicly": false,
"ready": true,
"dynamicallyScalable": true,
"extractable": false,
"sshKeyEnabled": true,
"created":"2016-10-24 2:40:29 PM EDT",
"zoneId":"ea901007-056b-4c50-bb3a-2dd635fce2ab",
"zoneName": "zone1",
"osTypeId":"d38dc1d9-dd34-4fdd-8f51-a973f8fe5f3b",
"osTypeName": "Other (64-bit)",
"availableInZones": [
"ea901007-056b-4c50-bb3a-2dd635fce2ab"
],
"hypervisor": "VMware",
"format": "OVA",
"nicAdapter": "e1000",
"rootDiskController": "scsi",
"keyboard": "uk"
}
}
GET /services/:service_code/:environment_name/templates/:id
Retrieve information about a public or private template of an environment.
| Attributes | |
|---|---|
idUUID |
The id of the template |
namestring |
The name of the template |
descriptionstring |
The description of the template |
defaultUsernamestring |
The default username of the template |
sizelong |
The size of the template in bytes |
availablePubliclyboolean |
true if public to everyone. Your custom templates will always be private |
readyboolean |
true if the template is ready to be used for a new instance |
dynamicallyScalableboolean |
true if you can dynamically scale an instance with this template |
extractableboolean |
true if you want the template to be downloadable from a generated URL |
createdstring |
The creation date of the template |
osTypeIdUUID |
Id of the OS type |
osTypeNamestring |
The OS type of the template (e.g. Ubuntu, CentOS...) |
sshEnabledboolean |
false if you want to enable sshKey for the template |
zoneIdUUID |
The zone id that the template is available in. Empty if available in multiple zones |
zoneNamestring |
The zone id that the template is available in. Empty if available in multiple zones |
availableInZonesarray[UUID] |
List of all zone ids that the template is available in |
hypervisorstring |
The name of the hypervisor |
formatstring |
The template format for the chosen hypervisor |
nicAdapterstring |
VMWare only The network interface controller name. Empty if not selected.Values: e1000, pcnet32, vmxnet2 or vmxnet3 |
rootDiskControllerstring |
VMWare only The root disk controller name. Empty if not selected.Values: ide, scsi for CloudStack version up to 4.4. Values: ide, scsi, osdefault, pvscsi, lsilogic, lsisas1068, buslogic for CloudStack version 4.5 and up |
keyboardstring |
VMWare only The keyboard type name. Empty if not selected.Values: us, uk, jp, sc |
Import a template
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/templates"
Request body example:
{
"name": "debian",
"description":"This is my template",
"url":"http://somewhere.com/template-vmware.ova",
"hypervisor":"VMWare",
"format":"OVA",
"keyboard":"us",
"nicAdapter":"vmxnet3",
"osTypeId": "53161a9c-6019-11e7-914a-0200246f00c5",
"osTypeName": "Debian GNU/Linux 7(64-bit)",
"zoneId":"e2cf7fa0-c3c2-4a39-9f8d-ee01ac3546cd"
}
POST /services/:service_code/:environment_name/templates
Import a template.
| Required | |
|---|---|
namestring |
The name of the template |
descriptionstring |
The description of the template |
urlstring |
The URL where the template is hosted. Both http and https URLs are supported |
zoneIdUUID |
The zone where it will be available. If there is only 1 zone, the field is optional |
hypervisorstring |
The name of the hypervisor |
formatstring |
The template format for the chosen hypervisor |
osTypeIdUUID |
Id of the OS type |
osTypeNamestring |
The OS type of the template (e.g. Ubuntu, CentOS...) |
| Optional | |
|---|---|
defaultUsernamestring |
The default username of the template |
sizelong |
The size of the template in bytes |
availablePubliclyboolean |
true if public to everyone. Your custom templates will always be private |
dynamicallyScalableboolean |
true if you can dynamically scale an instance with this template |
extractableboolean |
true if you want the template to be downloadable from a generated URL |
nicAdapterstring |
VMWare only The network interface controller name. Empty if not selected.Values: e1000, pcnet32, vmxnet2 or vmxnet3 |
rootDiskControllerstring |
VMWare only The root disk controller name. Empty if not selected.Values: ide, scsi for CloudStack version up to 4.4. Values: ide, scsi, osdefault, pvscsi, lsilogic, lsisas1068, buslogic for CloudStack version 4.5 and up |
keyboardstring |
VMWare only The keyboard type name. Empty if not selected.Values: us, uk, jp, sc |
passwordEnabledboolean |
false if want to set the reset password feature |
sshEnabledboolean |
false if you want to enable sshKey for the template |
Update a template
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/templates/162cdfcb-45e5-4aa6-81c4-124c94621bdb?operation=update"
Request body example:
{
"description":"This is my updated template description"
}
POST /services/:service_code/:environment_name/templates/:id/operation=update
Update a template.
| Required | |
|---|---|
namestring |
The name of the template |
descriptionstring |
The description of the template |
| Optional | |
|---|---|
formatstring |
The template format for the chosen hypervisor |
osTypeIdUUID |
Id of the OS type |
passwordEnabledboolean |
false if want to set the reset password feature |
sshEnabledboolean |
false if you want to enable sshKey for the template |
defaultUsernamestring |
The default username of the template |
dynamicallyScalableboolean |
true if you can dynamically scale an instance with this template |
nicAdapterstring |
VMWare only The network interface controller name. Empty if not selected.Values: e1000, pcnet32, vmxnet2 or vmxnet3 |
rootDiskControllerstring |
VMWare only The root disk controller name. Empty if not selected.Values: ide, scsi for CloudStack version up to 4.4. Values: ide, scsi, osdefault, pvscsi, lsilogic, lsisas1068, buslogic for CloudStack version 4.5 and up |
keyboardstring |
VMWare only The keyboard type name. Empty if not selected.Values: us, uk, jp, sc |
Delete a template
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/templates/162cdfcb-45e5-4aa6-81c4-124c94621bdb"
DELETE /services/:service_code/:environment_name/templates/:id
Delete a private template.
ISOs
An ISO is a disk image that is a copy of a file system. A bootable ISO can be used to create an instance. Otherwise, an ISO may be attached to an existing instance.
List ISOs
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/isos"
The above command returns a JSON structured like this:
{
"data": [{
"id": "0b3fea04-b1ed-48cf-921d-96795dfe9a81",
"name": "ubuntu",
"description": "Example ISO",
"architectureWidth": 64,
"size": 52428800,
"ready": true,
"bootable": true,
"availablePublicly": false,
"extractable": false,
"osTypeId":"d38dc1d9-dd34-4fdd-8f51-a973f8fe5f3b",
"osTypeName": "Other (64-bit)",
"zoneId":"ea901007-056b-4c50-bb3a-2dd635fce2ab",
"zoneName": "zone1",
"created": "2017-12-21 4:41:33 PM Z",
"availableInZones": ["ea901007-056b-4c50-bb3a-2dd635fce2ab"]
}],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/isos
Retrieve a list of all ISOs of an environment.
| Attributes | |
|---|---|
idUUID |
The id of the ISO |
namestring |
The name of the ISO |
descriptionstring |
The description of the ISO |
architectureWidthstring |
Number of bits |
sizelong |
The size of the ISO in bytes |
readyboolean |
true if the ISO is ready to be used |
bootableboolean |
true if the ISO can be used for a new instance |
osTypeIdUUID |
Id of th OS type |
osTypeNamestring |
The OS type of the ISO (e.g. Ubuntu, CentOS...) |
zoneIdUUID |
The zone id that the ISO is available in. Empty if available in multiple zones |
zoneNamestring |
The zone id that the ISO is available in. Empty if available in multiple zones |
createdstring |
The date the template was created |
availableInZonesList[String] |
The list of zone ids that the ISO is available in |
Retrieve a ISO
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/isos/162cdfcb-45e5-4aa6-81c4-124c94621bdb"
The above command returns a JSON structured like this:
{
"data": {
"id": "0b3fea04-b1ed-48cf-921d-96795dfe9a81",
"name": "ubuntu",
"description": "Example ISO",
"architectureWidth": 64,
"size": 52428800,
"ready": true,
"bootable": true,
"availablePublicly": false,
"extractable": false,
"osTypeId":"d38dc1d9-dd34-4fdd-8f51-a973f8fe5f3b",
"osTypeName": "Other (64-bit)",
"zoneId":"ea901007-056b-4c50-bb3a-2dd635fce2ab",
"zoneName": "zone1",
"created": "2017-12-21 4:41:33 PM Z",
"availableInZones": ["ea901007-056b-4c50-bb3a-2dd635fce2ab"]
}
}
GET /services/:service_code/:environment_name/isos/:id
Retrieve information about a public or private ISO of an environment.
| Attributes | |
|---|---|
idUUID |
The id of the ISO |
namestring |
The name of the ISO |
descriptionstring |
The description of the ISO |
architectureWidthstring |
Number of bits |
sizelong |
The size of the ISO in bytes |
readyboolean |
true if the ISO is ready to be used |
bootableboolean |
true if the ISO can be used for a new instance |
extractableboolean |
true if the template allows download from a generated URL |
osTypeIdUUID |
Id of th OS type |
osTypeNamestring |
The OS type of the ISO (e.g. Ubuntu, CentOS...) |
zoneIdUUID |
The zone id that the ISO is available in. Empty if available in multiple zones |
zoneNamestring |
The zone id that the ISO is available in. Empty if available in multiple zones |
createdstring |
The date the template was created |
availableInZonesList[String] |
The list of zone ids that the ISO is available in |
Import ISO
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/isos"
Request body example:
{
"name": "windows",
"description":"This is my ISO",
"url":"http://somewhere.com/somefile.iso",
"zoneId":"d342520b-94aa-4e44-b066-6c18c9e4d65b"
}
POST /services/:service_code/:environment_name/isos
Import an ISO.
| Required | |
|---|---|
namestring |
The name of the ISO |
descriptionstring |
The description of the ISO |
urlstring |
The URL where the ISO is hosted. N.B. only http protocol is supported |
zoneIdUUID |
The zone where it will be available. If there is only 1 zone, the field is optional |
| Optional | |
|---|---|
bootableboolean |
Indicates if the ISO is bootable or not. If provided, the osTypeId must be provided. |
osTypeIdUUID |
The OS type of the image. Must only be provided if bootable is true. |
Attach an ISO to an instance
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/testing/isos/e922e5fc-8fee-4688-ad93-c9ef5d7eb685?operation=attach"
Request body example:
{
"instanceId": "c043e651-8b3f-4941-b47f-5ecb77f3423b"
}
POST /services/:service_code/:environment_name/isos/:id?operation=attach
Attach an existing, non-bootable ISO to an instance. Each instance may have only one ISO attached at a time.
| Required | |
|---|---|
instanceIdUUID |
The id of the instance to which the ISO will be attached |
Detach the ISO from an instance
See the Detach the ISO from an instance endpoint under Instances.
Generate a download URL for an ISO
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/testing/isos/e922e5fc-8fee-4688-ad93-c9ef5d7eb685?operation=generateDownloadUrl"
# No parameters required
POST /services/:service_code/:environment_name/isos/:id?operation=generateDownloadUrl
Generate a URL that can be used to download an extractable ISO. The URL may also be used to import the ISO into another region. To be able to generate the download URL, the ISO must have been imported with the extractable flag set to true. The download URL will be placed in the url field of the task result.
Delete an ISO
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/isos/84fc07a8-c6a3-4538-b493-11ce69ea3c88"
DELETE /services/:service_code/:environment_name/isos/:id
Delete an ISO.
SSH keys
SSH keys can be assigned to default users of instances by using the associate SSH key operation.
List SSH keys
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/sshkeys"
The above command returns a JSON structured like this:
{
"data": [{
"name": "mellon",
"fingerprint": "91:8d:71:ca:2d:2c:ad:97:26:db:cb:c3:df:9a:e9:b6"
}],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/sshkeys
Retrieve a list of all SSH keys in an environment.
| Attributes | |
|---|---|
namestring |
The name of the SSH key |
fingerprintstring |
A short sequence of bytes used to identify the SSH key. |
Retrieve an SSH key
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/sshkeys/mellon"
The above command returns a JSON structured like this:
{
"data": {
"name": "mellon",
"fingerprint": "91:8d:71:ca:2d:2c:ad:97:26:db:cb:c3:df:9a:e9:b6"
}
}
GET /services/:service_code/:environment_name/sshkeys/:name
Retrieve information about an SSH key of an environment.
| Attributes | |
|---|---|
namestring |
The name of the SSH key |
fingerprintstring |
A short sequence of bytes used to identify the SSH key. |
Affinity groups
Affinity groups are a way of influencing on which host an instance will be deployed. An anti-affinity group (the only type of affinity group we support) allows you to put instances on different hosts to increase fault-tolerance. In the unlikely event of a host failure, your services would still be up on another host (assuming you distribute your services on multiple instances).
List affinity groups
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/affinitygroups"
The above command returns a JSON structured like this:
{
"data": [{
"id": "d4fd794f-66e1-4906-a720-d0afb04bd517",
"name": "gnr",
"type":"host anti-affinity",
"instanceIds": [
"92b4df86-fee3-4610-8167-78332b86362f"
]
}],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/affinitygroups
Retrieve a list of all affinity groups in an environment.
| Attributes | |
|---|---|
idUUID |
The id of the affinity group |
namestring |
The name of the affinity group |
typestring |
The type of affinity group. We only support anti-affinity |
instanceIdsArray[UUID] |
The ids of the instances in the affinity group |
Retrieve an affinity group
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/affinitygroups/d4fd794f-66e1-4906-a720-d0afb04bd517"
The above command returns a JSON structured like this:
{
"data": {
"id": "d4fd794f-66e1-4906-a720-d0afb04bd517",
"name": "gnr",
"type": "host anti-affinity",
"instanceIds": [
"92b4df86-fee3-4610-8167-78332b86362f"
]
}
}
GET /services/:service_code/:environment_name/affinitygroups/:id
Retrieve information about an affinity group.
| Attributes | |
|---|---|
idUUID |
The id of the affinity group |
namestring |
The name of the affinity group |
typestring |
The type of affinity group. We only support anti-affinity |
instanceIdsArray[UUID] |
The ids of the instances in the affinity group |
Create an affinity group
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/affinitygroups"
Request body example:
{
"name": "gnr",
"description": "My affinity group",
"type": "host anti-affinity",
"instanceIds": [
"92b4df86-fee3-4610-8167-78332b86362f"
]
}
POST /services/:service_code/:environment_name/affinitygroups
Create an affinity group and add instances to it.
| Required | |
|---|---|
namestring |
The name of the new affinity group |
descriptionstring |
A description of the affinity group |
typestring |
The type of new affinity group. We only support anti-affinity |
instanceIdsArray[UUID] |
The ids of the instances in the affinity group |
Update an affinity group
curl -X PUT \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/affinitygroups/d4fd794f-66e1-4906-a720-d0afb04bd517"
Request body example:
{
"instanceIds": [
"92b4df86-fee3-4610-8167-78332b86362f",
"105f8b5e-5482-4bf5-88ca-7d7b7f431e3e"
]
}
PUT /services/:service_code/:environment_name/affinitygroups/:id
Update the list of instances in the affinity group.
| Required | |
|---|---|
namestring |
The name of the new affinity group |
descriptionstring |
A description of the affinity group |
typestring |
The type of new affinity group. We only support anti-affinity |
instanceIdsArray[UUID] |
The ids of the instances in the affinity group |
Delete an affinity group
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/affinitygroups/d4fd794f-66e1-4906-a720-d0afb04bd517"
DELETE /services/:service_code/:environment_name/affinitygroups/:id
Delete an existing affinity group.
Networking
VPCs
A Virtual Private Cloud (VPC) is a logically isolated section of CloudMC, where you can build a multi-network application architecture.
List VPCs
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/vpcs"
The above command returns a JSON structured like this:
{
"data": [{
"id": "9fe8e398-06d6-482c-8f55-b805bde4d3cc",
"name": "MyVPC",
"description": "Some VPC",
"cidr": "10.155.24.0/22",
"zoneId": "04afdbd1-e32d-4999-86d0-96703736dded",
"zoneName": "QC-1",
"state": "Enabled",
"networkDomain": "hello.world",
"vpcOfferingId": "21a40b85-5fa9-440f-ab77-5e560073b584",
"requiresUpgrade": false,
"sourceNatIp": "172.31.3.253",
"vpnStatus": "Disabled"
}],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/vpcs
Retrieve a list of all VPCs of an environment.
| Attributes | |
|---|---|
idUUID |
The id of the VPC |
namestring |
The name of the VPC |
descriptionstring |
The description of the VPC |
cidrstring |
The CIDR of a VPC |
zoneIdstring |
The id of the zone where the VPC was created |
zoneNamestring |
The name of the zone where the VPC was created |
statestring |
The state of the VPC |
networkDomainstring |
A custom DNS suffix at the level of a network |
requiresUpgradestring |
true if the VPC needs to be upgraded |
sourceNatIpstring |
The source NAT IP of the VPC |
vpnStatusstring |
The status of the VPN. The status can be ENABLED or DISABLED |
Retrieve a VPC
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/vpcs/ad5bcae8-ee8b-4ee8-a7a4-381c25444b8e"
The above command returns a JSON structured like this:
{
"data": {
"id": "9fe8e398-06d6-482c-8f55-b805bde4d3cc",
"name": "MyVPC",
"description": "Some VPC",
"cidr": "10.155.24.0/22",
"zoneId": "04afdbd1-e32d-4999-86d0-96703736dded",
"zoneName": "QC-1",
"state": "Enabled",
"networkDomain": "hello.world",
"vpcOfferingId": "21a40b85-5fa9-440f-ab77-5e560073b584",
"requiresUpgrade": false,
"sourceNatIp": "172.31.3.253",
"vpnStatus": "Disabled"
}
}
GET /services/:service_code/:environment_name/vpcs/:id
Retrieve information about a VPC.
| Attributes | |
|---|---|
idUUID |
The id of the VPC |
namestring |
The name of the VPC |
descriptionstring |
The description of the VPC |
cidrstring |
The CIDR of a VPC |
zoneIdstring |
The id of the zone where the VPC was created |
zoneNamestring |
The name of the zone where the VPC was created |
statestring |
The state of the VPC |
networkDomainstring |
A custom DNS suffix at the level of a network |
requiresUpgradestring |
true if the VPC needs to be upgraded |
sourceNatIpstring |
The source NAT IP of the VPC |
vpnStatusstring |
The status of the VPN. The status can be ENABLED or DISABLED |
Create a VPC
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/vpcs"
Request body example:
{
"name": "my_vpc",
"description": "My prod VPC",
"vpcOfferingId": "21a40b85-5fa9-440f-ab77-5e560073b584",
"networkDomain": "hello.world"
}
POST /services/:service_code/:environment_name/vpcs
Create a VPC in an environment.
| Required | |
|---|---|
namestring |
The name of the new VPC |
descriptionstring |
The description of the new VPC |
vpcOfferingIdUUID |
The id of the VPC offering to use for the new VPC |
| Optional | |
|---|---|
networkDomainstring |
A custom DNS suffix at the level of a network |
Update a VPC
curl -X PUT \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/vpcs/d77e1ab1-0320-4504-83c5-e78b431c7577"
Request body example:
{
"name": "my_updated_vpc",
"description": "My prod VPC"
}
PUT /services/:service_code/:environment_name/vpcs
Update an existing VPC in your environment.
| Optional | |
|---|---|
namestring |
The new name of the VPC |
descriptionstring |
The new description of the VPC |
Destroy a VPC
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/vpcs/ad5bcae8-ee8b-4ee8-a7a4-381c25444b8e"
DELETE /services/:service_code/:environment_name/vpcs/:id
Destroy an existing VPC. To delete a VPC, you must first delete all the networks in the VPC.
Restart a VPC
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/vpcs/ad5bcae8-ee8b-4ee8-a7a4-381c25444b8e?operation=restart"
POST /services/:service_code/:environment_name/vpcs/:id?operation=restart
Restart the router of a VPC.
Networks
A network is an isolated network with its own VLANs and CIDR list, where you can place groups of resources, such as instances. They can exist as VPC subnets, or as simple isolated networks, provided the appropriate network offerings exist.
List networks
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/networks"
The above command returns a JSON structured like this:
{
"data": [{
"id": "8ef7539c-c9ba-49f3-a484-a08f4ffb2234",
"name": "Frontend",
"description": "default network",
"vpcId": "12b8c150-b444-482a-8411-c08eaccb0a3b",
"vpcName": "SomeVPC",
"zoneId": "04afdbd1-e32d-4999-86d0-96703736dded",
"zoneName": "QC-1",
"cidr": "10.169.254.0/24",
"gateway": "10.169.254.1",
"netmask": "255.255.255.0",
"networkAclId": "9ba3ec65-2e1d-11e4-8e05-42a29a39fc92",
"networkAclName": "default_allow",
"networkOfferingId": "9593f0df-573a-43c4-a107-a5c704a7cfee",
"networkOfferingName": "Load Balanced Network",
"networkOfferingDescription": "Offering for Isolated Vpc networks with Source Nat service enabled",
"state": "Implemented"
}],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/networks
Retrieve a list of all networks of an environment.
| Attributes | |
|---|---|
idUUID |
The id of the network |
namestring |
The name of the network |
descriptionstring |
The description of the network |
vpcIdUUID |
The id of the VPC where the network was created |
vpcNamestring |
The name of the VPC where the network was created |
zoneIdstring |
The id of the zone where the network was created |
zoneNamestring |
The name of the zone where the network was created |
cidrstring |
The cidr of the network |
gatewaystring |
The gateway of the network |
netmaskstring |
The netmask of the network |
networkAclIdUUID |
The id of the network ACL of the network |
networkAclNamestring |
The name of the network ACL of the network |
networkOfferingIdUUID |
The id of the network offering of the network |
networkOfferingNamestring |
The name of the network offering of the network |
networkOfferingDescriptionstring |
The description of the network offering of the network |
statestring |
The state of the network. Allocated if no instances where created in the network yet, Implemented otherwise. |
| Query Parameters | |
|---|---|
vpc_idUUID |
Filter the list to only retrieve the networks of a VPC |
zone_idUUID |
Filter the list to only retrieve the networks in a specific zone |
Retrieve a network
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/networks/ad5bcae8-ee8b-4ee8-a7a4-381c25444b8e"
The above command returns a JSON structured like this:
{
"data": {
"id": "8ef7539c-c9ba-49f3-a484-a08f4ffb2234",
"name": "Frontend",
"description": "default network",
"vpcId": "12b8c150-b444-482a-8411-c08eaccb0a3b",
"vpcName": "SomeVPC",
"zoneId": "04afdbd1-e32d-4999-86d0-96703736dded",
"zoneName": "QC-1",
"cidr": "10.169.254.0/24",
"gateway": "10.169.254.1",
"netmask": "255.255.255.0",
"networkAclId": "9ba3ec65-2e1d-11e4-8e05-42a29a39fc92",
"networkAclName": "default_allow",
"networkOfferingId": "9593f0df-573a-43c4-a107-a5c704a7cfee",
"networkOfferingName": "Load Balanced Network",
"networkOfferingDescription": "Offering for Isolated Vpc networks with Source Nat service enabled",
"state": "Implemented"
}
}
GET /services/:service_code/:environment_name/networks/:id
Retrieve information about a network.
| Attributes | |
|---|---|
idUUID |
The id of the network |
namestring |
The name of the network |
descriptionstring |
The description of the network |
vpcIdUUID |
The id of the VPC where the network was created |
vpcNamestring |
The name of the VPC where the network was created |
zoneIdstring |
The id of the zone where the network was created |
zoneNamestring |
The name of the zone where the network was created |
cidrstring |
The cidr of the network |
gatewaystring |
The gateway of the network |
netmaskstring |
The netmask of the network |
networkAclIdUUID |
The id of the network ACL of the network |
networkAclNamestring |
The name of the network ACL of the network |
networkOfferingIdUUID |
The id of the network offering of the network |
networkOfferingNamestring |
The name of the network offering of the network |
networkOfferingDescriptionstring |
The description of the network offering of the network |
statestring |
The state of the network. Allocated if no instances where created in the network yet, Implemented otherwise. |
Create a network
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/networks"
Request body example:
{
"name": "my_network",
"description": "My production network",
"vpcId": "b1932c7c-0b85-450f-92b9-bfdeb3e80804",
"networkOfferingId": "c5d4ffcd-56e2-407a-8b4d-06082b7365c4",
"networkAclId": "9ba3ec65-2e1d-11e4-8e05-42a29a39fc92"
}
POST /services/:service_code/:environment_name/networks
Create a network in an environment.
If the network offering is a VPC subnet offering (indicated by the vpcOnly flag on the offering), the vpcId and networkAclId are required fields.
| Required | |
|---|---|
namestring |
The name of the new network |
descriptionstring |
The description of the new network |
networkOfferingIdUUID |
The id of the network offering to use for the network |
| Required (if VPC subnet) | |
|---|---|
vpcIdUUID |
The id of the VPC where to create the network |
networkAclIdUUID |
The id of the network ACL to use for the network |
| For isolated networks | |
|---|---|
netmaskstring |
The netmask to use for this network. e.g. 255.255.255.0 |
gatewaystring |
The network's gateway. e.g. 10.0.0.1 |
Update a network
curl -X PUT \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/networks/9572d2ea-a60d-478a-a75e-8ed31f2641f1"
Request body example:
{
"name": "my_updated_network",
"description": "My updated production network"
}
POST /services/:service_code/:environment_name/networks/:id
Update an existing network in an environment.
| Required | |
|---|---|
namestring |
The updated name of the network |
descriptionstring |
The updated description of the network |
Delete a network
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/networks/9572d2ea-a60d-478a-a75e-8ed31f2641f1"
DELETE /services/:service_code/:environment_name/networks/:id
Delete an existing network in an environment To delete a network, you must first delete all the instances in the network.
Replace the network ACL
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/networks/9572d2ea-a60d-478a-a75e-8ed31f2641f1?operation=replace"
Request body example:
{
"name": "my_updated_network",
"description": "My updated production network"
}
POST /services/:service_code/:environment_name/networks/:id?operation=replace
Replace the network ACL for a VPC subnet.
| Required | |
|---|---|
networkAclIdstring |
The id of the network ACL to use for the network |
Network ACLs
Manage access control lists and their rules. To apply an ACL to a VPC subnet, replace the ACL of a network.
List network ACLs
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/networkacls?vpc_id=eb763d03-9935-4cd4-8a42-99134e242ccb"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "736d0c2e-d6b5-43fc-bcf0-732fce9a509e",
"vpcId": "eb763d03-9935-4cd4-8a42-99134e242ccb",
"name": "custom-1",
"description": "Allows network egress"
},
{
"id": "3246de94-e7e7-11e3-9187-06669c0000ad",
"name": "default_allow",
"description": "Default Network ACL Allow All"
},
{
"id": "32467792-e7e7-11e3-9187-06669c0000ad",
"name": "default_deny",
"description": "Default Network ACL Deny All"
}
],
"metadata": {
"recordCount": 3
}
}
GET /services/:service_code/:environment_name/networkacls?vpc_id=:vpc_id
Retrieve a list of network ACLs in a VPC.
| Attributes | |
|---|---|
idUUID |
The id of the network ACL |
namestring |
The name of the network ACL |
descriptionstring |
The description of the network ACL |
vpcIdUUID |
The VPC where this rule is available. Not present on default_allow and default_deny ACLs |
| Query Parameters | |
|---|---|
vpc_idUUID |
Filter the list to only retrieve the network ACLs of a specific VPC |
Retrieve a network ACL
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/networkacls/736d0c2e-d6b5-43fc-bcf0-732fce9a509e"
The above command returns a JSON structured like this:
{
"data": {
"id": "736d0c2e-d6b5-43fc-bcf0-732fce9a509e",
"vpcId": "eb763d03-9935-4cd4-8a42-99134e242ccb",
"name": "custom-1",
"description": "Allows network egress"
}
}
GET /services/:service_code/:environment_name/networkacls/:id
Retrieve a specific network ACL by its id.
| Attributes | |
|---|---|
idUUID |
The id of the network ACL |
namestring |
The name of the network ACL |
descriptionstring |
The description of the network ACL |
vpcIdUUID |
The VPC where this rule is available. Not present on default_allow and default_deny ACLs |
Create network ACL
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/networkacls"
POST /services/:service_code/:environment_name/networkacls
Create a new network ACL associated to a VPC.
| Required | |
|---|---|
namestring |
The name of the network ACL |
descriptionstring |
The description of the network ACL |
vpcIdUUID |
Networks of this VPC will be able to use the new ACL |
Delete a network ACL
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/networkacls/736d0c2e-d6b5-43fc-bcf0-732fce9a509e"
DELETE /services/:service_code/:environment_name/networkacls/:id
Delete an ACL and all of its rules.
List a network ACL's rules
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/networkaclrules?network_acl_id=3246de94-e7e7-11e3-9187-06669c0000ad"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "3247167a-e7e7-11e3-9187-06669c0000ad",
"networkAclId": "3246de94-e7e7-11e3-9187-06669c0000ad",
"ruleNumber": "2",
"description":"Allow all egress",
"cidr": "0.0.0.0/0",
"action": "Allow",
"protocol": "ALL",
"trafficType": "Egress",
"state": "Active"
},
{
"id": "3246fdb6-e7e7-11e3-9187-06669c0000ad",
"networkAclId": "3246de94-e7e7-11e3-9187-06669c0000ad",
"ruleNumber": "1",
"description":"Allow all ingress",
"cidr": "0.0.0.0/0",
"action": "Allow",
"protocol": "ALL",
"trafficType": "Ingress",
"state": "Active"
}
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/networkaclrules?network_acl_id=:network_acl_id
List a network ACL's rules.
| Attributes | |
|---|---|
idUUID |
The id of the network ACL rule |
networkAclIdUUID |
The id of the network ACL that this rule belongs to |
ruleNumberint |
The relative position of this rule in its ACL |
cidrCIDR |
The network addresses targeted by this rule |
actionstring |
What to do with traffic matched by this rule. Either Allow or Deny |
protocolstring |
The protocols targeted by this rule. TCP, UDP, ICMP, or ALL |
trafficTypestring |
The direction of traffic targeted by this rule. Either Ingress or Egress |
statestring |
The state of this rule. Either Active or Inactive |
descriptionstring |
The description of the rule |
| Query Parameters | |
|---|---|
network_acl_idUUID |
Filter the list to only retrieve the rules of a specific network ACL |
Retrieve a network ACL rule
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/networkaclrules/3247167a-e7e7-11e3-9187-06669c0000ad"
The above command returns a JSON structured like this:
{
"data": {
"id": "3247167a-e7e7-11e3-9187-06669c0000ad",
"networkAclId": "3246de94-e7e7-11e3-9187-06669c0000ad",
"ruleNumber": "2",
"description":"Allow all egress",
"cidr": "0.0.0.0/0",
"action": "Allow",
"protocol": "ALL",
"trafficType": "Egress",
"state": "Active"
}
}
GET /services/:service_code/:environment_name/networkaclrules/:id
| Attributes | |
|---|---|
idUUID |
The id of the network ACL rule |
networkAclIdUUID |
The id of the network ACL that this rule belongs to |
ruleNumberint |
The relative position of this rule in its ACL |
cidrCIDR |
The network addresses targeted by this rule |
actionstring |
What to do with traffic matched by this rule. Either Allow or Deny |
protocolstring |
The protocols targeted by this rule. TCP, UDP, ICMP, or ALL |
trafficTypestring |
The direction of traffic targeted by this rule. Either Ingress or Egress |
statestring |
The state of this rule. Either Active or Inactive |
descriptionstring |
The description of the rule |
Create a network ACL rule
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/networkaclrules"
POST /services/:service_code/:environment_name/networkaclrules
| Required | |
|---|---|
networkAclIdUUID |
The id of the network ACL to add this rule to |
ruleNumberint |
The relative position of this rule in its ACL |
cidrCIDR |
The network addresses targeted by this rule |
actionstring |
What to do with traffic matched by this rule. Either Allow or Deny |
protocolstring |
The protocols targeted by this rule. TCP, UDP, ICMP, or ALL |
trafficTypestring |
The direction of traffic targeted by this rule. Either Ingress or Egress |
| Protocol-specific | |
|---|---|
startPortint |
The start of the port range targeted by this rule. Required if the protocol is TCP or UDP |
endPortint |
The end of the port range targeted by this rule. Required if the protocol is TCP or UDP |
icmpTypeint |
ICMP message type. Required if the protocol is ICMP |
icmpCodeint |
ICMP message error code. Required if the protocol is ICMP |
| Optional | |
|---|---|
descriptionstring |
The description of the rule |
Update a network ACL rule
curl -X PUT \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/networkaclrules/3247167a-e7e7-11e3-9187-06669c0000ad"
PUT /services/:service_code/:environment_name/networkaclrules/:id
Update a network ACL rule.
| Optional | |
|---|---|
ruleNumberint |
The relative position of this rule in its ACL |
cidrCIDR |
The network addresses targeted by this rule |
descriptionstring |
The description of the rule |
actionstring |
What to do with traffic matched by this rule. Either Allow or Deny |
protocolstring |
The protocols targeted by this rule. TCP, UDP, ICMP, or ALL |
trafficTypestring |
The direction of traffic targeted by this rule. Either Ingress or Egress |
startPortint |
The start of the port range targeted by this rule |
endPortint |
The end of the port range targeted by this rule |
icmpTypeint |
ICMP message type |
icmpCodeint |
ICMP message error code |
Delete a network ACL rule
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/networkaclrules/3247167a-e7e7-11e3-9187-06669c0000ad"
DELETE /services/:service_code/:environment_name/networkaclrules/:id
Delete a specific rule of a network ACL.
Public IPs
List public IPs
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/publicipaddresses"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "0ed72307-e33d-4d41-90b7-7d2b4f0d1ae0",
"instances": [
{
"id": "986cfea3-4a94-407d-b915-eb2d49e4323f",
"name": "i-pdube-F49"
}
],
"ipAddress": "69.196.164.98",
"networkId": "def89cb6-f897-435a-ad7f-6b2d05ab11e6",
"networkName": "web",
"purposes": [
"PORT_FORWARDING"
],
"state": "Allocated",
"vpcId": "0687f5ce-89f9-47c8-9f58-c522455d56eb",
"vpcName": "secondary",
"zoneId": "ea901007-056b-4c50-bb3a-2dd635fce2ab",
"zoneName": "ON-1"
},
{
"id": "10001e7d-b4ef-489b-836e-0619a383bc8d",
"ipAddress": "208.80.152.201",
"purposes": [
"SOURCE_NAT"
],
"state": "Allocated",
"vpcId": "0687f5ce-89f9-47c8-9f58-c522455d56eb",
"vpcName": "primary",
"zoneId": "ea901007-056b-4c50-bb3a-2dd635fce2ab",
"zoneName": "ON-1"
}
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/publicipaddresses
List allocated public IP addresses.
| Attributes | |
|---|---|
idUUID |
The id of the public IP |
instancesArray[Instance] |
The associated instances includes: id,name |
ipAddressstring |
The IP address (e.g. 208.80.154.224) |
networkIdUUID |
The associated network id |
networkNamestring |
The associated network name |
purposesArray[string] |
The list of purposes of the IP address.Possible values: STATIC_NAT, PORT_FORWARDING, LOAD_BALANCING, SOURCE_NAT or SOURCE_NAT and VPN |
statestring |
The state of the public IP |
vpcIdUUID |
The id of the VPC |
vpcNamestring |
The name of the VPC |
zoneIdUUID |
The id of the zone |
zoneNamestring |
The name of the zone |
| Query Parameters | |
|---|---|
vpc_idUUID |
Filter the list to only retrieve the public IPs in a specific VPC |
instance_idUUID |
Filter the list to only retrieve the public IPs associated to a specific instance |
Retrieve a public IP
curl -X GET -H "MC-Api-Key: your_api_key"
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/publicipaddresses/10001e7d-b4ef-489b-836e-0619a383bc8d"
The above command returns a JSON structured like this:
{
"data": {
"id": "10001e7d-b4ef-489b-836e-0619a383bc8d",
"ipAddress": "208.80.152.201",
"purposes": [
"SOURCE_NAT"
],
"state": "Allocated",
"vpcId": "0687f5ce-89f9-47c8-9f58-c522455d56eb",
"vpcName": "primary",
"zoneId": "ea901007-056b-4c50-bb3a-2dd635fce2ab",
"zoneName": "ON-1"
}
}
GET /services/:service_code/:environment_name/publicipaddresses/:id
Retrieve a public IP address.
| Attributes | |
|---|---|
idUUID |
The id of the public IP |
instancesArray[Instance] |
The associated instances includes: id,name |
ipAddressstring |
The IP address (e.g. 208.80.154.224) |
networkIdUUID |
The associated network id |
networkNamestring |
The associated network name |
purposesArray[string] |
The list of purposes of the IP address.Possible values: STATIC_NAT, PORT_FORWARDING, LOAD_BALANCING, SOURCE_NAT or SOURCE_NAT and VPN |
statestring |
The state of the public IP |
vpcIdUUID |
The id of the VPC |
vpcNamestring |
The name of the VPC |
zoneIdUUID |
The id of the zone |
zoneNamestring |
The name of the zone |
Acquire a public IP
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/publicipaddresses"
Request body example:
{
"vpcId": "0687f5ce-89f9-47c8-9f58-c522455d56eb"
}
POST /services/:service_code/:environment_name/publicipaddresses
Acquire a public IP address for a VPC.
| Required | |
|---|---|
vpcIdUUID |
The id of the VPC where to acquire the public IP |
Release a public IP
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/publicipaddresses/a723b2b1-e343-4ea1-afe0-bf345a99a92b"
DELETE /services/:service_code/:environment_name/publicipaddresses/:id
Release a public IP. When acquiring a public IP, you are not guaranteed to receive a previously owned public IP, so be careful when releasing public IPs.
Enable static NAT
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/publicipaddresses/a723b2b1-e343-4ea1-afe0-bf345a99a92b?operation=enableStaticNat"
Request body example:
{
"privateIpId": "5e30609d-7098-4d93-8317-3ecfe316ed00"
}
POST /services/:service_code/:environment_name/publicipaddresses/:id?operation=enableStaticNat
Enable static NAT on a public IP address.
| Required | |
|---|---|
privateIpIdstring |
The private IP id of the instance which is to be available on that IP. It can also be done on a secondary IP id. |
Disable static NAT
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/publicipaddresses/a723b2b1-e343-4ea1-afe0-bf345a99a92b?operation=disableStaticNat"
POST /services/:service_code/:environment_name/publicipaddresses/:id?operation=disableStaticNat
Disable static NAT on that public IP.
Port forwarding rules
Port forwarding allows traffic from external hosts to services offered by applications in your VPCs. A port forwarding rule is a mapping of public IP ports to private IP ports (i.e. forwards traffic from a public IP to an instance).
List port forwarding rules
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/portforwardingrules"
The above command returns a JSON structured like this:
{
"data": [{
"id": "bf145d1e-7beb-42b8-bd2c-1a316aeb9aef",
"ipAddress": "74.121.244.23",
"ipAddressId": "747e30d0-a0cd-48ba-b7d8-77a2f7e10504",
"privatePortStart": "8080",
"privatePortEnd": "8080",
"publicPortStart": "80",
"publicPortEnd": "80",
"protocol": "TCP",
"instanceId": "d7328dd9-882e-4d08-8ad2-c74c2d493689",
"instanceName": "my_app_instance",
"networkId": "7388f551-4163-4467-b49b-58e9310d7207",
"vpcId": "39907f0a-c253-42b8-b02d-337e00e9851e",
"privateIp": "10.155.24.145",
"privateIpId": "10.155.24.145 "
}],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/portforwardingrules
Retrieve a list of all port forwarding rules of an environment.
| Attributes | |
|---|---|
idUUID |
The id of the port forwarding rule |
ipAddressstring |
The ip address of the public IP associated to this port forwarding rule |
ipAddressIdUUID |
The id of the public IP associated to this port forwarding rule |
privatePortStartstring |
The start of the private port range |
privatePortEndstring |
The end of the private port range |
publicPortStartstring |
The start of the public port range |
publicPortEndstring |
The end of the public port range |
protocolstring |
The protocol of the port forwarding rule (e.g. TCP, UDP) |
instanceIdUUID |
The id of the instance of the port forwarding rule |
instanceNamestring |
The name of the instance of the port forwarding rule |
networkIdUUID |
The id of the network of the port forwarding rule |
vpcIdUUID |
The id of the VPC of the port forwarding rule |
privateIpstring |
The private IP address of the instance where the traffic will be forwarded |
privateIpIdUUID |
The id of private IP address of the instance where traffic will be forwarded |
| Query Parameters | |
|---|---|
instance_idUUID |
Filter the list to only retrieve the port forwarding rules of an instance |
Retrieve a port forwarding rule
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/portforwardingrules/ad5bcae8-ee8b-4ee8-a7a4-381c25444b8e"
The above command returns a JSON structured like this:
{
"data": {
"id": "bf145d1e-7beb-42b8-bd2c-1a316aeb9aef",
"ipAddress": "74.121.244.23",
"ipAddressId": "747e30d0-a0cd-48ba-b7d8-77a2f7e10504",
"privatePortStart": "8080",
"privatePortEnd": "8080",
"publicPortStart": "80",
"publicPortEnd": "80",
"protocol": "TCP",
"instanceName": "my_app_instance",
"instanceId": "d7328dd9-882e-4d08-8ad2-c74c2d493689",
"networkId": "7388f551-4163-4467-b49b-58e9310d7207",
"vpcId": "39907f0a-c253-42b8-b02d-337e00e9851e",
"privateIp": "10.155.24.145",
"privateIpId": "fc9d60a5-a8f8-4d01-a63f-f1731440063f"
}
}
GET /services/:service_code/:environment_name/portforwardingrules/:id
Retrieve information about a port forwarding rule.
| Attributes | |
|---|---|
idUUID |
The id of the port forwarding rule |
ipAddressstring |
The ip address of the public IP associated to this port forwarding rule |
ipAddressIdUUID |
The id of the public IP associated to this port forwarding rule |
privatePortStartstring |
The start of the private port range |
privatePortEndstring |
The end of the private port range |
publicPortStartstring |
The start of the public port range |
publicPortEndstring |
The end of the public port range |
protocolstring |
The protocol of the port forwarding rule (e.g. TCP, UDP) |
instanceIdUUID |
The id of the instance of the port forwarding rule |
instanceNamestring |
The name of the instance of the port forwarding rule |
networkIdUUID |
The id of the network of the port forwarding rule |
vpcIdUUID |
The id of the VPC of the port forwarding rule |
privateIpstring |
The private IP address of the instance where requests will be forwarded |
privateIpIdUUID |
The id of private IP address of the instance where requests will be forwarded |
Create a port forwarding rule
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/portforwardingrules"
Request body example:
{
"ipAddressId": "4daf6ce5-a8b1-47d2-96b3-8edda63d891c",
"instanceId": "0ec9ee23-f9dd-4830-acb6-7f8d4469673a",
"protocol": "TCP",
"privatePortStart": "8080",
"privatePortEnd": "8080",
"publicPortStart": "80",
"publicPortEnd": "80"
}
POST /services/:service_code/:environment_name/portforwardingrules
Create a port forwarding rule for a public IP.
| Required | |
|---|---|
ipAddressIdUUID |
The id of the public IP where the port forwarding should be created |
protocolstring |
The protocol (e.g. TCP, UDP) to forward |
privatePortStartstring |
The start of the private port range |
privatePortEndstring |
The end of the private port range |
publicPortStartstring |
The start of the public port range |
publicPortEndstring |
The end of the public port range |
| Optional | |
|---|---|
instanceIdUUID |
The id of the instance that will have a port forwarded (it will use the default private port) |
privateIpIdUUID |
The id of the private IP to forward |
Delete a port forwarding rule
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/portforwardingrules/7d22b390-cbb3-4df6-96c6-52901ccb63c0"
DELETE /services/:service_code/:environment_name/portforwardingrules/:id
Delete an existing port forwarding rule.
Load balancer rules
List load balancer rules
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/loadbalancerrules?public_ip_id=eb763d03-9935-4cd4-8a42-99134e242ccb"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "32804ef2-dea6-4b07-b507-b3562bb9844a",
"name": "web_lbr",
"networkId": "394873ef-8655-49b6-8096-58b99c4e2347",
"publicIp": "172.31.3.202",
"publicIpId": "44ebac5d-18cc-4eea-ab59-7a2af0691c88",
"publicPort": "80",
"privatePort": "80",
"algorithm": "roundrobin",
"protocol": "ssl",
"stickinessMethod": "AppCookie",
"instanceIds": [
"d7048640-35d4-4a4f-8193-f4837da7e861"
],
"sslCertificateId": "b1bea50a-e5f0-4b1e-bc0d-1dde909ac49a",
"stickinessPolicyId": "217c1140-4146-4af0-92e9-ad47d4ff5ba9",
"stickinessPolicyParameters": {
"mode": "test",
"indirect": "false",
"domain": "some_domain",
"postonly": "false",
"nocache": "true",
"cookieName": "test"
}
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/loadbalancerrules?public_ip_id=:public_ip_id
Retrieve a list of load balancer rules.
| Attributes | |
|---|---|
idUUID |
The id of the load balancer rule |
namestring |
The name of the load balancer rule |
networkIdstring |
The network id of the load balancer rule |
publicIpUUID |
The public IP of this load balancer rule |
publicIpIdstring |
The id of the public IP of this load balancer rule |
publicPortint |
The public port of this load balancer rule |
privatePortint |
The private port of this load balancer rule |
algorithmstring |
The algorithm to use for this load balancer rule |
protocolstring |
The protocol to load balance |
stickinessMethodstring |
The stickiness policy of the load balancer rule |
stickinessPolicyParametersMap[string,string] |
The stickiness policy parameters of the load balancer rule |
instanceIdsArray[string] |
The ids of the instances being load balanced |
| Query Parameters | |
|---|---|
public_ip_idUUID |
Filter the list to only retrieve the load balancer rules of a public IP |
Retrieve a load balancer rule
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/loadbalancerrules/f8ed7f44-449c-4510-848c-dc18e6665db1"
The above command returns a JSON structured like this:
{
"data": {
"id": "f8ed7f44-449c-4510-848c-dc18e6665db1",
"name": "web_lbr",
"networkId": "394873ef-8655-49b6-8096-58b99c4e2347",
"publicIp": "172.31.3.202",
"publicIpId": "44ebac5d-18cc-4eea-ab59-7a2af0691c88",
"publicPort": "22",
"privatePort": "22",
"algorithm": "roundrobin",
"protocol": "tcp",
"stickinessMethod": "LbCookie",
"instanceIds": [
"056cbb23-9021-4df7-b458-721ed9153ba9"
],
"stickinessPolicyId": "29a1946c-5b59-4ab1-b9b8-5c73444b1c10",
"stickinessPolicyParameters": {
"mode": "test",
"indirect": "false",
"domain": "some_domain",
"postonly": "false",
"nocache": "true",
"cookieName": "test"
}
}
}
GET /services/:service_code/:environment_name/loadbalancerrules/:id
Retrieve a specific load balancer rule by its id.
| Attributes | |
|---|---|
idUUID |
The id of the load balancer rule |
namestring |
The name of the load balancer rule |
networkIdstring |
The network id of the load balancer rule |
publicIpUUID |
The public IP of this load balancer rule |
publicIpIdstring |
The id of the public IP of this load balancer rule |
publicPortint |
The public port of this load balancer rule |
privatePortint |
The private port of this load balancer rule |
algorithmstring |
The algorithm to use for this load balancer rule |
protocolstring |
The protocol to load balance |
stickinessMethodstring |
The stickiness policy of the load balancer rule |
stickinessPolicyParametersMap[string,string] |
The stickiness policy parameters of the load balancer rule |
instanceIdsArray[string] |
The ids of the instances being load balanced |
Create a load balancer rule
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/loadbalancerrules"
Request body example:
{
"name": "test",
"publicIpId": "44ebac5d-18cc-4eea-ab59-7a2af0691c88",
"networkId": "093f6208-8a56-4035-8e71-3e39029fc5aa",
"publicPort": "80",
"privatePort": "80",
"algorithm": "roundrobin",
"protocol": "ssl",
"stickinessMethod": "AppCookie",
"instanceIds": [
"d7048640-35d4-4a4f-8193-f4837da7e861"
],
"sslCertificateId": "b1bea50a-e5f0-4b1e-bc0d-1dde909ac49a",
"stickinessPolicyParameters": {
"holdtime": 3600000
}
}
POST /services/:service_code/:environment_name/loadbalancerrules
Create a new load balancer rule associated to a public IP.
| Required | |
|---|---|
namestring |
The name of the load balancer rule |
publicIpIdstring |
The id of the public IP of this load balancer rule |
publicPortint |
The public port of this load balancer rule |
privatePortint |
The private port of this load balancer rule |
algorithmstring |
The algorithm to use for this load balancer rule (roundrobin, leastconn or source) |
protocolstring |
The protocol to load balance (TCP, UDP or TCP-PROXY) |
| Optional (required if public IP already assigned a network) | |
|---|---|
networkIdstring |
The network id of the load balancer rule |
| Optional | |
|---|---|
stickinessMethodstring |
The stickiness policy of the load balancer rule |
stickinessPolicyParametersMap[string, object] |
The stickiness policy parameters of the load balancer rule |
instanceIdsArray[string] |
The ids of the instances being load balanced |
sslCertificateIdUUID |
The id of the SSL certificate for the load balancer rule. Can only be used with SSL protocol. |
| LbCookie parameters | |
|---|---|
cookieNamestring |
Name of the cookie to be inserted by the load balancer for load balancing |
modestring |
rewrite, insert or prefix. rewrite: This keyword indicates that the cookie will be provided by the server and that the load balancer will have to modify its value to set the server's identifier in it. insert: This keyword indicates that the persistence cookie will have to be inserted by the load balancer in server responses if the client did not already have a cookie that would have permitted it to access this server. prefix: This keyword indicates that instead of relying on a dedicated cookie for the persistence, an existing one will be completed. |
nocacheboolean |
This option is recommended in conjunction with the insert mode when there is a cache between the client and the load balancer, as it ensures that a cacheable response will be tagged non-cacheable if a cookie needs to be inserted. |
indirectboolean |
When this option is specified, no cookie will be emitted to a client which already has a valid one for the server which has processed the request. |
postonlyboolean |
This option ensures that cookie insertion will only be performed on responses to POST requests. |
domainstring |
This option allows to specify the domain at which a cookie is inserted. |
| AppCookie parameters | |
|---|---|
cookieNamestring |
Name of the cookie to be inserted by the application for load balancing. |
modestring |
This option allows to change the URL parser mode. path-parameters(default) will look for the appsession cookie in the path parameters. query-parameters will look for the appsession cookie in the query parameters. |
lengthstring |
The maximum number of characters to check in the cookie value. |
holdtimeboolean |
Time in milliseconds that the cookie should be saved. |
requestLearnboolean |
If true, then it will be able to learn the cookie found in the request in case the server does not specify any in response. |
prefixstring |
If true, then it will match on the cookie prefix (or URL parameter prefix). The appsession value is the data following this prefix. |
| SourceBased parameters | |
|---|---|
tableSizestring |
The maximum number of entries that can be stored in the table. |
expiresstring |
Defines the maximum duration of an entry in the table since it was last created, refreshed or matched. The expiration delay is defined using the standard time format, similarly as the various timeouts. |
For more information, please consult section 4.2 of the HAProxy configuration manual. (AppCookie, LbCookie, SourceBased)
Update a load balancer rule
curl -X PUT \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/loadbalancerrules/3247167a-e7e7-11e3-9187-06669c0000ad"
Request body example:
{
"name": "test",
"algorithm": "roundrobin"
}
PUT /services/:service_code/:environment_name/loadbalancerrules/:id
Update a load balancer rule.
| Optional | |
|---|---|
namestring |
The name of the load balancer rule |
algorithmstring |
The algorithm of the load balancer rule (roundrobin, leastconn or source) |
Update instances of a load balancer rule
curl -X PUT \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/loadbalancerrules/3247167a-e7e7-11e3-9187-06669c0000ad"
Request body example:
{
"instanceIds": [
"95d034b5-b902-440c-b430-120efaed9caf", "60df0bc2-f59b-4608-8147-1b8ac4a39add"
]
}
PUT /services/:service_code/:environment_name/loadbalancerrules/:id?operation=updateInstances
Update instances of a load balancer rule.
| Required | |
|---|---|
instanceIdsArray[String] |
The instances of the load balancer rule |
Update stickiness policy of a load balancer rule
curl -X PUT \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/loadbalancerrules/3247167a-e7e7-11e3-9187-06669c0000ad"
Request body example:
{
"stickinessMethod": "LbCookie",
"stickinessPolicyParameters": {
"mode": "test",
"indirect": "false",
"domain": "some_domain",
"postonly": "false",
"nocache": "true",
"cookieName": "test"
}
}
PUT /services/:service_code/:environment_name/loadbalancerrules/:id?operation=updateStickiness
Update instances of a load balancer rule.
| Required | |
|---|---|
stickinessMethodstring |
The stickiness policy for the load balancer rule |
stickinessPolicyParametersMap[String, String] |
The parameters for the stickiness policy of the load balancer rule |
See Create a load balance rule for stickiness policy parameters documentation.
Delete a load balancer rule
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/loadbalancerrules/736d0c2e-d6b5-43fc-bcf0-732fce9a509e"
DELETE /services/:service_code/:environment_name/loadbalancerrules/:id
Delete a load balancer rule.
Ingress rules
Manage inbound traffic rules for isolated networks.
List ingress rules
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/ingressrules"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "f6c7f86f-1e28-42fd-804f-0416a201a778",
"networkId": "858d3ab6-04c9-43ef-9e83-07f28df59323",
"publicIp": "172.31.3.202",
"publicIpId": "44ebac5d-18cc-4eea-ab59-7a2af0691c88",
"sourceCidr": "10.2.1.0/25",
"protocol": "TCP",
"startPort": "80",
"endPort": "90",
"state": "Active"
},
{
"id": "f1863d10-e7ec-4f17-8cdd-0e4046643b0b",
"networkId": "858d3ab6-04c9-43ef-9e83-07f28df59323",
"publicIp": "172.31.3.202",
"publicIpId": "44ebac5d-18cc-4eea-ab59-7a2af0691c88",
"sourceCidr": "10.2.1.0/24",
"protocol": "UDP",
"startPort": "",
"endPort": "",
"state": "Active"
},
{
"id": "d860f2e7-ad15-4cb0-8477-6aa439245d1f",
"networkId": "858d3ab6-04c9-43ef-9e83-07f28df59323",
"publicIp": "172.31.3.202",
"publicIpId": "44ebac5d-18cc-4eea-ab59-7a2af0691c88",
"sourceCidr": "10.2.1.0/24",
"protocol": "ICMP",
"icmpType": "3",
"icmpCode": "5",
"state": "Active"
}
],
"metadata": {
"recordCount": 3
}
}
GET /services/:service_code/:environment_name/ingressrules
List ingress rules.
| Attributes | |
|---|---|
idUUID |
The id of the ingress rule |
networkIdstring |
The id of the isolated network the rule applies to |
publicIpstring |
The public IP of this ingress rule |
publicIpIdUUID |
The id of the public IP of this ingress rule |
sourceCidrstring |
The source cidr |
protocolstring |
The protocol the rule applies to. Possible values: TCP, UDP, ICMP |
startPortstring |
The start port (for TCP/UDP protocols only). Can be empty for all ports. |
endPortstring |
The end port (for TCP/UDP protocols only). Can be empty to match the start port value. |
icmpTypestring |
The ICMP type (for ICMP protocol only) |
icmpCodestring |
The ICMP code (for ICMP protocol only) |
statestring |
The state. Possible values: Active, Inactive |
| Query Parameters | |
|---|---|
network_idUUID |
Filter the list to only retrieve the ingress rules of a specific Network |
public_ip_idUUID |
Filter the list to only retrieve the ingress rules of a specific public IP |
Retrieve a specific ingress rule
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/ingressrules/f1863d10-e7ec-4f17-8cdd-0e4046643b0b"
The above command returns a JSON structured like this:
{
"data": {
"id": "f1863d10-e7ec-4f17-8cdd-0e4046643b0b",
"networkId": "858d3ab6-04c9-43ef-9e83-07f28df59323",
"publicIp": "172.31.3.202",
"publicIpId": "44ebac5d-18cc-4eea-ab59-7a2af0691c88",
"sourceCidr": "10.2.1.0/24",
"protocol": "UDP",
"startPort": "80",
"endPort": "80",
"state": "Active"
}
}
GET /services/:service_code/:environment_name/ingressrules/:id
Retrieve an ingress rule by its id.
| Attributes | |
|---|---|
idUUID |
The id of the ingress rule |
networkIdstring |
The id of the isolated network the rule applies to |
publicIpstring |
The public IP of this ingress rule |
publicIpIdUUID |
The id of the public IP of this ingress rule |
sourceCidrstring |
The source cidr |
protocolstring |
The protocol the rule applies to. Possible values: TCP, UDP, ICMP |
startPortstring |
The start port (for TCP/UDP protocols only). Can be empty for all ports. |
endPortstring |
The end port (for TCP/UDP protocols only). Can be empty to match the start port value. |
icmpTypestring |
The ICMP type (for ICMP protocol only) |
icmpCodestring |
The ICMP code (for ICMP protocol only) |
statestring |
The state. Possible values: Active, Inactive |
Create an ingress rule
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/ingressrules"
POST /services/:service_code/:environment_name/ingressrules
| Required | |
|---|---|
networkIdstring |
The id of the isolated network the rule applies to |
sourceCidrstring |
The source cidr |
protocolstring |
The protocols targeted by this rule (TCP, UDP, ICMP). |
| Protocol-specific | |
|---|---|
publicIpIdUUID |
The id of the public IP where the ingress be applied. If not provided, a new public IP will be acquired. |
startPortstring |
The start of the port range targeted by this rule. Required if the protocol is TCP or UDP. If left empty, all ports will be opened. |
endPortstring |
The end of the port range targeted by this rule. Only valid if the protocol is TCP or UDP. If left empty, it will match the startPort value. |
icmpTypestring |
ICMP message type. Required if the protocol is ICMP |
icmpCodestring |
ICMP message error code. Required if the protocol is ICMP |
Delete an ingress rule
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/ingressrules/3247167a-e7e7-11e3-9187-06669c0000ad"
DELETE /services/:service_code/:environment_name/ingressrules/:id
Delete a specific ingress rule.
Egress rules
Manage outbound traffic rules for isolated networks
List egress rules
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/egressrules"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "f6c7f86f-1e28-42fd-804f-0416a201a778",
"networkId": "858d3ab6-04c9-43ef-9e83-07f28df59323",
"sourceCidr": "10.2.1.0/25",
"destinationCidr": "0.0.0.0/0",
"protocol": "ALL",
"state": "Active"
},
{
"id": "d860f2e7-ad15-4cb0-8477-6aa439245d1f",
"networkId": "858d3ab6-04c9-43ef-9e83-07f28df59323",
"sourceCidr": "10.2.1.0/24",
"destinationCidr": "",
"protocol": "ICMP",
"icmpType": "3",
"icmpCode": "5",
"state": "Active",
"allPortsAllowed": false
},
{
"id": "f1863d10-e7ec-4f17-8cdd-0e4046643b0b",
"networkId": "858d3ab6-04c9-43ef-9e83-07f28df59323",
"sourceCidr": "10.2.1.0/24",
"destinationCidr": "",
"protocol": "UDP",
"startPort": "",
"endPort": "",
"state": "Active",
"allPortsAllowed": true
}
],
"metadata": {
"recordCount": 3
}
}
GET /services/:service_code/:environment_name/egressrules
List egress rules.
| Attributes | |
|---|---|
idUUID |
The id of the egress rule |
networkIdstring |
The id of the network the rule applies to |
sourceCidrstring |
The source cidr |
destinationCidrstring |
The destination cidr |
protocolstring |
The protocol the rule applies to. Possible values: TCP, UDP, ICMP, ALL |
startPortstring |
The start port (for TCP/UDP protocols only) |
endPortstring |
The end port (for TCP/UDP protocols only) |
allPortsAllowedboolean |
The flag indicating all the port range selection (for TCP/UDP protocols only) |
icmpTypestring |
The ICMP type (for ICMP protocol only) |
icmpCodestring |
The ICMP code (for ICMP protocol only) |
statestring |
The state. Possible values: Active, Inactive |
| Query Parameters | |
|---|---|
network_idUUID |
Filter the list to only retrieve the egress rules of a specific Network |
Retrieve an egress rule
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/egressrules/f1863d10-e7ec-4f17-8cdd-0e4046643b0b"
The above command returns a JSON structured like this:
{
"data": {
"id": "f1863d10-e7ec-4f17-8cdd-0e4046643b0b",
"networkId": "858d3ab6-04c9-43ef-9e83-07f28df59323",
"sourceCidr": "10.2.1.0/24",
"destinationCidr": "",
"protocol": "UDP",
"startPort": "",
"endPort": "",
"state": "Active",
"allPortsAllowed": true
}
}
GET /services/:service_code/:environment_name/egressrules/:id
Retrieve an egress rule by its id.
| Attributes | |
|---|---|
idUUID |
The id of the egress rule |
networkIdstring |
The id of the network the rule applies to |
sourceCidrstring |
The source cidr |
destinationCidrstring |
The destination cidr |
protocolstring |
The protocol the rule applies to |
startPortstring |
The start port (for TCP/UDP protocols only) |
endPortstring |
The end port (for TCP/UDP protocols only) |
allPortsAllowedboolean |
The flag indicating all the port range selection (for TCP/UDP protocols only) |
icmpTypestring |
The ICMP message type (for ICMP protocol only) |
icmpCodestring |
The ICMP message error code (for ICMP protocol only) |
statestring |
The state. Possible values: Active, Inactive |
Create an egress rule
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/egressrules"
POST /services/:service_code/:environment_name/egressrules
| Required | |
|---|---|
networkIdstring |
The id of the network the rule applies to |
sourceCidrstring |
The source cidr |
protocolstring |
The protocols targeted by this rule. TCP, UDP, ICMP, or ALL |
| Optional | |
|---|---|
destinationCidrstring |
The destination cidr |
| Protocol-specific | |
|---|---|
startPortstring |
The start of the port range targeted by this rule. Required if the protocol is TCP or UDP |
endPortstring |
The end of the port range targeted by this rule. Required if the protocol is TCP or UDP |
allPortsAllowedboolean |
The flag indicating the selection of all the port range, i.e. 1-65535. Required if the protocol is TCP or UDP. Default value: false |
icmpTypestring |
ICMP message type. Required if the protocol is ICMP |
icmpCodestring |
ICMP message error code. Required if the protocol is ICMP |
Delete an egress rule
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/egressrules/3247167a-e7e7-11e3-9187-06669c0000ad"
DELETE /services/:service_code/:environment_name/egressrules/:id
Delete a specific egress rule.
NICs
List NICs
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/nics"
The above command returns a JSON structured like this:
{
"data": [{
"id": "fff1f45a-8350-4c87-be43-947b96d01ebd",
"name": "NIC-0",
"ipAddress": "10.169.253.165",
"isDefault": true,
"networkId": "d2243d4c-0dd8-4f8c-9ab4-4b1d285d5642",
"networkName": "Backend",
"gateway": "10.169.253.1",
"netmask": "255.255.255.0",
"instanceId": "b6145e8b-abd3ta-456c-832c-f3db86a6acfe",
"vpcId": "5aa9f5d7-55a9-43bf-bd2c-78a6bae1b267",
"vpcName": "default-vpc",
"secondaryIps": [
{
"id": "9c28e297-5d23-41a3-a167-34dc24f1df19",
"ipAddress": "10.169.253.124"
}
]
}],
"metadata": {
"recordCount": 1
}
}
GET :service_code/:environment_name/nics
Retrieve a list of all NICs.
| Attributes | |
|---|---|
idUUID |
The id of the NIC |
namestring |
The name of the NIC |
ipAddressstring |
The IP address of the NIC |
isDefaultstring |
true if it's the default NIC of the instance (i.e. it will be the private IP on the instance) |
networkIdUUID |
The id of the network of the NIC |
networkNamestring |
The name of the network of the NIC |
gatewaystring |
The gateway of the network associated with the NIC |
netmaskstring |
The netmask of the network associated with the NIC |
instanceIdstring |
The id of the instance associated with the NIC |
vpcIdstring |
The id of the VPC associated with the NIC |
vpcNamestring |
The name of the VPC associated with the NIC |
secondaryIpsSecondaryIP |
The list of secondary IPs of the NIC includes: id, ipAddress |
| Query Parameters | |
|---|---|
instance_idUUID |
Filter the list to only retrieve the NICs of a specific instance |
network_idUUID |
Filter the list to only retrieve the NICs of a specific network |
Retrieve a NIC
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/nics/fff1f45a-8350-4c87-be43-947b96d01ebd"
The above command returns a JSON structured like this:
{
"data": {
"id": "fff1f45a-8350-4c87-be43-947b96d01ebd",
"name": "NIC-0",
"ipAddress": "10.169.253.165",
"isDefault": true,
"networkId": "d2243d4c-0dd8-4f8c-9ab4-4b1d285d5642",
"networkName": "Backend",
"gateway": "10.169.253.1",
"netmask": "255.255.255.0",
"instanceId": "b6145e8b-abd3ta-456c-832c-f3db86a6acfe",
"vpcId": "5aa9f5d7-55a9-43bf-bd2c-78a6bae1b267",
"vpcName": "default-vpc",
"secondaryIps": [
{
"id": "9c28e297-5d23-41a3-a167-34dc24f1df19",
"ipAddress": "10.169.253.124"
}
]
}
}
GET /services/:service_code/:environment_name/nics/:id
Retrieve an existing NIC.
| Attributes | |
|---|---|
idUUID |
The id of the NIC |
namestring |
The name of the NIC |
ipAddressstring |
The IP address of the NIC |
isDefaultstring |
true if it's the default NIC of the instance (i.e. it will be the private IP on the instance) |
networkIdUUID |
The id of the network of the NIC |
networkNamestring |
The name of the network of the NIC |
gatewaystring |
The gateway of the network associated with the NIC |
netmaskstring |
The netmask of the network associated with the NIC |
instanceIdstring |
The id of the instance associated with the NIC |
vpcIdstring |
The id of the VPC associated with the NIC |
vpcNamestring |
The name of the VPC associated with the NIC |
secondaryIpsSecondaryIP |
The list of secondary IPs of the NIC includes: id, ipAddress |
Create a NIC
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/nics"
Request body example:
{
"networkId": "d67e986d-fe04-4827-836e-1697ede8ed30",
"instanceId": "96330eea-4424-46ca-825c-82fdd051d8c3"
}
POST /services/:service_code/:environment_name/nics
Create a NIC for an instance in a specific network. You can only have one NIC per network.
| Required | |
|---|---|
networkIdstring |
The id of the network where to create the NIC |
instanceIdstring |
The id of the instance where to attach the NIC |
Delete a NIC
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/nics/63ef1efe-225f-4e05-bc79-b3e457a041e2"
DELETE /services/:service_code/:environment_name/nics/:id
Delete an existing NIC. The NIC you're trying to delete must not be the default one and must not be associated to a load balancing rule and/or a port forwarding rule.
Set a NIC as default
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/nics/63ef1efe-225f-4e05-bc79-b3e457a041e2?operation=setDefault"
POST /services/:service_code/:environment_name/nics/:id?operation=setDefault
Set an existing NIC as the default NIC of an instance.
Remote access VPNs
Remote access VPNs allow users to connect to VPCs through secure connections.
List remote access VPNs
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/remoteaccessvpns"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "10001e7d-b4ef-489b-836e-0619a383bc8d",
"publicIpAddress": "69.196.164.31",
"publicIpAddressId": "10001e7d-b4ef-489b-836e-0619a383bc8d",
"state": "Disabled"
},
{
"id": "8925406c-8051-467e-a0ca-c48caa5bf670",
"presharedKey": "Kwth4JYUfXXmtMG4X7vAwRPH",
"publicIpAddress": "69.196.164.223",
"publicIpAddressId": "8925406c-8051-467e-a0ca-c48caa5bf670",
"state": "Enabled"
}
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/remoteaccessvpns
List remote access VPNs.
| Attributes | |
|---|---|
idUUID |
The id of the remote access VPN |
presharedKeystring |
The VPN's preshared key |
publicIpAddressstring |
The public IP (e.g. 208.80.154.224) |
publicIpAddressIdstring |
The id of the public IP |
statestring |
The state. Possible values: Enabled, Disabled. |
| Query Parameters | |
|---|---|
vpc_idUUID |
Filter the list to only retrieve the VPN information of a specific VPC |
network_idUUID |
Filter the list to only retrieve the VPN information of a specific Network |
Retrieve a remote access VPN
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/remoteaccessvpns/10001e7d-b4ef-489b-836e-0619a383bc8d"
The above command returns a JSON structured like this:
{
"data": {
"id": "10001e7d-b4ef-489b-836e-0619a383bc8d",
"publicIpAddress": "69.196.164.31",
"publicIpAddressId": "10001e7d-b4ef-489b-836e-0619a383bc8d",
"state": "Disabled"
}
}
GET /services/:service_code/:environment_name/remoteaccessvpns/:id
Retrieve a remote access VPN.
| Attributes | |
|---|---|
idUUID |
The id of the remote access VPN |
presharedKeystring |
The VPN's preshared key |
publicIpAddressstring |
The public IP (e.g. 208.80.154.224) |
publicIpAddressIdstring |
The id of the public IP |
statestring |
The state. Possible values: Enabled, Disabled. |
VPN users
VPN users are the accounts that are allowed to connect to remote access VPNs.
List VPN users
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/vpnusers"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "5de76bf5-9f61-487a-a989-042b52882da4",
"username": "wilson"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/vpnusers
List VPN users.
| Attributes | |
|---|---|
idUUID |
The id of the remote access VPN user |
usernamestring |
The VPN user's username |
Retrieve a VPN user
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/vpnusers/5de76bf5-9f61-487a-a989-042b52882da4"
The above command returns a JSON structured like this:
{
"data": {
"id": "5de76bf5-9f61-487a-a989-042b52882da4",
"username": "wilson"
}
}
GET /services/:service_code/:environment_name/vpnusers/:id
Retrieve a VPN user.
| Attributes | |
|---|---|
idUUID |
The id of the remote access VPN user |
usernamestring |
The VPN user's username |
Delete a VPN user
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/vpnusers/5de76bf5-9f61-487a-a989-042b52882da4"
DELETE /services/:service_code/:environment_name/vpnusers/:id
Delete an existing remote access VPN user.
Site-to-site VPNs
A site-to-site VPN allows multiple sites to establish a secure connection over the public network. In our case, we are talking about a secure connection between your VPC and another network (e.g. VPC, offices).
List site-to-site VPNs
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/sitetositevpns"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "d49b2922-0581-4587-94df-6fe719327d0f",
"name": "stargate",
"state": "Connected",
"vpcId": "3fe7d82a-f4c4-4552-ac3b-787fdafed4e7",
"gateway":"19.19.19.19",
"cidrList":"10.12.0.2/22,10.0.0.0/24",
"ipSecPsk": "WtOBS9GRux2XtJPtHY2TUvrv",
"ikeEncryptionAlgorithm": "aes256",
"ikeHashAlgorithm": "sha1",
"ikeDhGroup":"modp1536",
"ikeLifetime":86400,
"espEncryptionAlgorithm":"aes256",
"espHashAlgorithm":"sha1",
"espPerfectForwardSecrecy":"modp1536",
"espLifetime":3600,
"dpd": false,
"forceEncap": false
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/sitetositevpns
Retrieve a list of all site-to-site VPNs in an environment.
| Attributes | |
|---|---|
idUUID |
The id of the site-to-site VPN |
namestring |
The name of the site-to-site VPN |
statestring |
The state of the site-to-site VPN. Can be Connected, Pending, Disconnected or Error. If disconnected, you can try to use the reset operation |
vpcIdUUID |
The VPC for which the site-to-site VPN was created. |
gatewaystring |
The gateway of the network you want to connect to. NOTE: you cannot use a gateway that has already been used by a site-to-site VPN in your environment |
cidrListstring |
Comma-separated list of CIDRs of the networks you want to connect to. |
ipSecPskstring |
IPSec pre-shared key. |
ikeEncryptionAlgorithmstring |
The Internet Key Exchange (IKE) policy for phase-1. The supported encryption algorithms are AES128, AES192, AES256, and 3DES. |
ikeHashAlgorithmstring |
The IKE hash for phase-1. The supported hash algorithms are SHA1 and MD5. |
ikeDhGroupstring |
A public-key cryptography protocol which allows two parties to establish a shared secret over an insecure communications channel. The supported options are Group-5 (1536-bit) and Group-2 (1024-bit). |
ikeLifetimeinteger |
The phase-1 lifetime of the security association in seconds. |
espEncryptionAlgorithmstring |
Encapsulating Security Payload (ESP) algorithm within phase-2. The supported encryption algorithms are AES128, AES192, AES256, and 3DES. |
espHashAlgorithmstring |
Encapsulating Security Payload (ESP) hash for phase-2. Supported hash algorithms are SHA1 and MD5. |
espPerfectForwardSecrecystring |
Perfect Forward Secrecy (or PFS) is the property that ensures that a session key derived from a set of long-term public and private keys will not be compromised. The supported options are Group-5 (1536-bit) and Group-2 (1024-bit). |
espLifetimeinteger |
The phase-2 lifetime of the security association in seconds |
dpdboolean |
A method to detect an unavailable Internet Key Exchange (IKE) peer. |
forceEncapboolean |
Force encapsulation for NAT Traversal |
| Query Parameters | |
|---|---|
vpc_idUUID |
Filter the list to only retrieve the site-to-site VPNs of a VPC |
Retrieve a site-to-site VPN
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/sitetositevpns/d49b2922-0581-4587-94df-6fe719327d0f"
The above command returns a JSON structured like this:
{
"data": {
"id": "d49b2922-0581-4587-94df-6fe719327d0f",
"name": "stargate",
"state": "Connected",
"vpcId": "3fe7d82a-f4c4-4552-ac3b-787fdafed4e7",
"gateway":"19.19.19.19",
"cidrList":"10.12.0.2/22,10.0.0.0/24",
"ipSecPsk": "WtOBS9GRux2XtJPtHY2TUvrv",
"ikeEncryptionAlgorithm": "aes256",
"ikeHashAlgorithm": "sha1",
"ikeDhGroup":"modp1536",
"ikeLifetime":86400,
"espEncryptionAlgorithm":"aes256",
"espHashAlgorithm":"sha1",
"espPerfectForwardSecrecy":"modp1536",
"espLifetime":3600,
"dpd": false,
"forceEncap": false
}
}
GET /services/:service_code/:environment_name/sitetositevpns/:id
Retrieve information about a site-to-site VPN.
| Attributes | |
|---|---|
idUUID |
The id of the site-to-site VPN |
namestring |
The name of the site-to-site VPN |
statestring |
The state of the site-to-site VPN. Can be Connected, Pending, Disconnected or Error. If disconnected, you can try to use the reset operation |
vpcIdUUID |
The VPC for which the site-to-site VPN was created. |
gatewaystring |
The gateway of the network you want to connect to. NOTE: you cannot use a gateway that has already been used by a site-to-site VPN in your environment |
cidrListstring |
Comma-separated list of CIDRs of the networks you want to connect to. |
ipSecPskstring |
IPSec pre-shared key. |
ikeEncryptionAlgorithmstring |
The Internet Key Exchange (IKE) policy for phase-1. The supported encryption algorithms are AES128, AES192, AES256, and 3DES. |
ikeHashAlgorithmstring |
The IKE hash for phase-1. The supported hash algorithms are SHA1 and MD5. |
ikeDhGroupstring |
A public-key cryptography protocol which allows two parties to establish a shared secret over an insecure communications channel. The supported options are Group-5 (1536-bit) and Group-2 (1024-bit). |
ikeLifetimeinteger |
The phase-1 lifetime of the security association in seconds. |
espEncryptionAlgorithmstring |
Encapsulating Security Payload (ESP) algorithm within phase-2. The supported encryption algorithms are AES128, AES192, AES256, and 3DES. |
espHashAlgorithmstring |
Encapsulating Security Payload (ESP) hash for phase-2. Supported hash algorithms are SHA1 and MD5. |
espPerfectForwardSecrecystring |
Perfect Forward Secrecy (or PFS) is the property that ensures that a session key derived from a set of long-term public and private keys will not be compromised. The supported options are Group-5 (1536-bit) and Group-2 (1024-bit). |
espLifetimeinteger |
The phase-2 lifetime of the security association in seconds |
dpdboolean |
A method to detect an unavailable Internet Key Exchange (IKE) peer. |
forceEncapboolean |
Force encapsulation for NAT Traversal |
Create a site-to-site VPN
# Here is the absolute minimum information required to create a new site-to-site VPN:
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/sitetositevpns"
Request body example:
{
"name": "stargate",
"vpcId": "3fe7d82a-f4c4-4552-ac3b-787fdafed4e7",
"gateway":"19.19.19.19",
"cidrList":"10.12.0.2/22,10.0.0.0/24",
"ipSecPsk": "WtOBS9GRux2XtJPtHY2TUvrv",
"ikeEncryptionAlgorithm": "aes256",
"ikeHashAlgorithm": "sha1",
"ikeDhGroup":"modp1536",
"ikeLifetime":86400,
"espEncryptionAlgorithm":"aes256",
"espHashAlgorithm":"sha1",
"espPerfectForwardSecrecy":"modp1536",
"espLifetime":3600,
"dpd": false,
"forceEncap": false
}
POST /services/:service_code/:environment_name/sitetositevpns
Create a site-to-site VPN.
| Required | |
|---|---|
namestring |
The name of the site-to-site VPN. Must be unique in the environment. |
vpcIdUUID |
The VPC for which the site-to-site VPN was created. |
gatewaystring |
The gateway of the network you want to connect to. NOTE: you cannot use a gateway that has already been used by a site-to-site VPN in your environment |
cidrListstring |
Comma-separated list of CIDRs of the networks you want to connect to. |
ipSecPskstring |
IPSec pre-shared key. |
ikeEncryptionAlgorithmstring |
The Internet Key Exchange (IKE) policy for phase-1. The supported encryption algorithms are AES128, AES192, AES256, and 3DES. |
ikeHashAlgorithmstring |
The IKE hash for phase-1. The supported hash algorithms are SHA1 and MD5. |
ikeDhGroupstring |
A public-key cryptography protocol which allows two parties to establish a shared secret over an insecure communications channel. The supported options are Group-5 (1536-bit) and Group-2 (1024-bit). |
ikeLifetimeinteger |
The phase-1 lifetime of the security association in seconds. |
espEncryptionAlgorithmstring |
Encapsulating Security Payload (ESP) algorithm within phase-2. The supported encryption algorithms are AES128, AES192, AES256, and 3DES. |
espHashAlgorithmstring |
Encapsulating Security Payload (ESP) hash for phase-2. Supported hash algorithms are SHA1 and MD5. |
espPerfectForwardSecrecystring |
Perfect Forward Secrecy (or PFS) is the property that ensures that a session key derived from a set of long-term public and private keys will not be compromised. The supported options are Group-5 (1536-bit) and Group-2 (1024-bit). |
espLifetimeinteger |
The phase-2 lifetime of the security association in seconds |
| Optional |
|---|
dpd
boolean | A method to detect an unavailable Internet Key Exchange (IKE) peer. Defaults to false
forceEncap
boolean | Force encapsulation for NAT Traversal. Defaults to false
Update a site-to-site VPN
# Here is the absolute minimum information required to update a site-to-site VPN:
curl -X PUT \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/sitetositevpns/d49b2922-0581-4587-94df-6fe719327d0f"
Request body example:
{
"name": "stargate",
"gateway":"19.19.19.19",
"cidrList":"10.12.0.2/22,10.0.0.0/24",
"ipSecPsk": "WtOBS9GRux2XtJPtHY2TUvrv",
"ikeEncryptionAlgorithm": "aes256",
"ikeHashAlgorithm": "sha1",
"ikeDhGroup":"modp1536",
"ikeLifetime":86400,
"espEncryptionAlgorithm":"aes256",
"espHashAlgorithm":"sha1",
"espPerfectForwardSecrecy":"modp1536",
"espLifetime":3600,
"dpd": false,
"forceEncap": false
}
POST /services/:service_code/:environment_name/sitetositevpns/:id
Update a site-to-site VPN.
| Optional | |
|---|---|
namestring |
The name of the site-to-site VPN. Must be unique in the environment. |
gatewaystring |
The gateway of the network you want to connect to. NOTE: you cannot use a gateway that has already been used by a site-to-site VPN in your environment |
cidrListstring |
Comma-separated list of CIDRs of the networks you want to connect to. |
ipSecPskstring |
IPSec pre-shared key. |
ikeEncryptionAlgorithmstring |
The Internet Key Exchange (IKE) policy for phase-1. The supported encryption algorithms are AES128, AES192, AES256, and 3DES. |
ikeHashAlgorithmstring |
The IKE hash for phase-1. The supported hash algorithms are SHA1 and MD5. |
ikeDhGroupstring |
A public-key cryptography protocol which allows two parties to establish a shared secret over an insecure communications channel. The supported options are Group-5 (1536-bit) and Group-2 (1024-bit). |
ikeLifetimeinteger |
The phase-1 lifetime of the security association in seconds. |
espEncryptionAlgorithmstring |
Encapsulating Security Payload (ESP) algorithm within phase-2. The supported encryption algorithms are AES128, AES192, AES256, and 3DES. |
espHashAlgorithmstring |
Encapsulating Security Payload (ESP) hash for phase-2. Supported hash algorithms are SHA1 and MD5. |
espPerfectForwardSecrecystring |
Perfect Forward Secrecy (or PFS) is the property that ensures that a session key derived from a set of long-term public and private keys will not be compromised. The supported options are Group-5 (1536-bit) and Group-2 (1024-bit). |
espLifetimeinteger |
The phase-2 lifetime of the security association in seconds |
dpdboolean |
A method to detect an unavailable Internet Key Exchange (IKE) peer. Defaults to false |
forceEncapboolean |
Force encapsulation for NAT Traversal. Defaults to false |
Delete a site-to-site VPN
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/sitetositevpns/d49b2922-0581-4587-94df-6fe719327d0f"
DELETE /services/:service_code/:environment_name/sitetositevpns/:id
Delete an existing site-to-site VPN.
Reset the connection of a site-to-site VPN
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/sitetositevpns/ca86b14f-20db-463d-b58a-9d3fa5959af2?operation=reset"
POST /services/:service_code/:environment_name/sitetositevpns/:id?operation=reset
Reset a site-to-site VPN.
Storage
Volumes
A volume is a virtual disk that provide storage for your instances. An OS volumes is created for every instance and it holds the OS of the instance. The size of this volume is usually pretty. A data volume is a volume that can be created and attached to an instance. It can also be detached and reattached to another instance.
List volumes
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/volumes"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "1bd672f4-b274-4371-a792-b0a6c6778cc7",
"name": "DOUGLAS-ADM",
"type": "os",
"creationDate": "2016-10-19T14:25:41-0400",
"instanceId": "b6145e8b-abd3-456c-832c-f3db86a6acfe",
"instanceName": "i-douglas-ADM",
"zoneId": "04afdbd1-e32d-4999-86d0-96703736dded",
"zoneName": "QC-1",
"state": "Ready",
"sizeInGb": 40
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/volumes
Retrieve a list of all volumes in an environment.
| Attributes | |
|---|---|
idUUID |
The id of the volume |
namestring |
The name of the volume |
typestring |
The type of the volume. os if it is a root volume of an instance, data otherwise |
creationDatestring |
The creation date of the volume |
instanceIdUUID |
The id of the instance to which the volume is attached |
instanceNamestring |
The name of the instance to which the volume is attached |
zoneIdUUID |
The id of the zone where the volume was created |
zoneNamestring |
The name of the zone where the volume was created |
statestring |
The state of the volume |
sizeInGbinteger |
The size in gigabytes of the volume |
| Query Parameters | |
|---|---|
typestring |
Filter the list to only retrieve the volumes of a specific type (os or data) |
instance_idUUID |
Filter the list to only retrieve the volumes of a specific instance |
Retrieve a volume
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/volumes/1bd672f4-b274-4371-a792-b0a6c6778cc7"
The above command returns a JSON structured like this:
{
"data": {
"id": "1bd672f4-b274-4371-a792-b0a6c6778cc7",
"name": "deep_thought_42",
"type": "data",
"creationDate": "2016-10-19T14:25:41-0400",
"instanceId": "b6145e8b-abd3-456c-832c-f3db86a6acfe",
"instanceName": "i-douglas-ADM",
"zoneId": "04afdbd1-e32d-4999-86d0-96703736dded",
"zoneName": "QC-1",
"diskOfferingId": "21ba9c9b-a31e-496e-983f-e3041525bf95",
"diskOfferingName": "50GB - 50 IOPS Min.",
"state": "Ready",
"sizeInGb": 40
}
}
GET /services/:service_code/:environment_name/volumes/:id
Retrieve information about an volume.
| Attributes | |
|---|---|
idUUID |
The id of the volume |
namestring |
The name of the volume |
typestring |
The type of the volume. os if it is a root volume of an instance, data otherwise |
creationDatestring |
The creation date of the volume |
instanceIdUUID |
The id of the instance to which the volume is attached |
instanceNamestring |
The name of the instance to which the volume is attached |
zoneIdUUID |
The id of the zone where the volume was created |
zoneNamestring |
The name of the zone where the volume was created |
statestring |
The state of the volume |
sizeInGbinteger |
The size in gigabytes of the volume |
Create a volume
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/testing/volumes"
Request body example:
{
"name": "my_volume",
"diskOfferingId": "166f85eb-b4a2-4000-8e0c-24104d551f60",
"instanceId": "c043e651-8b3f-4941-b47f-5ecb77f3423b"
}
POST /services/:service_code/:environment_name/volumes
Create a volume in an environment. It will attached to the specified instance.
| Required | |
|---|---|
| name string |
The name of the new volume |
| diskOfferingId UUID |
The disk offering to use for the volume |
| instanceId UUID |
The id of the instance to which the created volume will be attached |
Delete a volume
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/volumes/e922e5fc-8fee-4688-ad93-c9ef5d7eb685"
DELETE /services/:service_code/:environment_name/volumes/:id
Destroy an existing data volume. A volume can only be deleted if it's not attached to an instance.
Attach a volume to an instance
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/testing/volumes/e922e5fc-8fee-4688-ad93-c9ef5d7eb685?operation=attachToInstance"
Request body example:
{
"instanceId": "c043e651-8b3f-4941-b47f-5ecb77f3423b"
}
POST /services/:service_code/:environment_name/volumes/:id?operation=attachToInstance
Attach an existing data volume to an instance.
| Required | |
|---|---|
| instanceId UUID |
The id of the instance to which the created volume should be attached |
Detach a volume from an instance
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/testing/volumes/e922e5fc-8fee-4688-ad93-c9ef5d7eb685?operation=detachFromInstance"
POST /services/:service_code/:environment_name/volumes/:id?operation=detachFromInstance
Detach a data volume from an instance.
Create a volume snapshot
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/testing/volumes/4fe54594-a788-442c-b7a8-0237f7a4f70d?operation=createSnapshotFromVolume"
Request body example:
{
"snapshot": {
"name": "PreMigrationState",
"rapid": true
}
}
POST /services/:service_code/:environment_name/volumes/:id?operation=createSnapshotFromVolume
Create a snapshot of an existing volume. Note that the volume must be in its READY state to be able to take a snapshot of it.
| Optional | |
|---|---|
namestring |
A unique name to be given to the newly created snapshot. If this parameter is not provided then by default the concatenation of the instance name, volume name and the current timestamp is used. Eg: [instance.name]_[volume.name]_[timestamp] i-root-6E7_RapidVol_20190117153537 |
rapidboolean |
Indicates the location as to where the snapshot is supposed to be made. Setting this to true will ensure that the snapshot is created in the same primary storage as where the volume is. If false, then the snapshot is created in a secondary storage. Note: Rapid snapshots enable much faster volume and template creation than from regular snapshots, but at a higher expense. Not all volumes support the rapid snapshot option. |
Snapshots
A volume snapshot is a full image of a volume. They are often considered as backups, but in reality this is not 100% true since you have only the data written on disk. Volume Snapshots are typically used to derive new templates out of a running instance.
List snapshots
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/snapshots"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "33a27b8d-5a27-42a5-aec4-37606e372bda",
"name": "i-douglas-ADM_foo_20161116211009",
"state": "BackedUp",
"intervalType": "MANUAL",
"volumeId": "c779ca42-6966-41af-a7dc-23db4e41d4ee",
"volume": "ROOT-35545",
"volumeType": "ROOT-35545"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/snapshots
Retrieve a list of all snapshots in an environment.
| Attributes | |
|---|---|
idUUID |
The id of the snapshot |
namestring |
The name of the snapshot |
statestring |
The state of the snapshot |
intervalTypestring |
The interval type. MANUAL means that you created the snapshot manually (i.e. it's not a recurring snapshot) |
volumeIdUUID |
The id of the volume that was snapshotted |
volumestring |
The name of the volume that was snapshotted |
volumeTypestring |
The type of the volume that was snapshotted |
| Query Parameters | |
|---|---|
volume_idUUID |
Filter the list to only retrieve the snapshots of a specific volume |
Retrieve a snapshot
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/snapshots/1bd672f4-b274-4371-a792-b0a6c6778cc7"
The above command returns a JSON structured like this:
{
"data": {
"id": "33a27b8d-5a27-42a5-aec4-37606e372bda",
"name": "i-douglas-ADM_foo_20161116211009",
"state": "BackedUp",
"intervalType": "MANUAL",
"volumeId": "c779ca42-6966-41af-a7dc-23db4e41d4ee",
"volume": "ROOT-35545",
"volumeType": "ROOT-35545"
}
}
GET /services/:service_code/:environment_name/snapshots/:id
Retrieve information about a snapshot.
| Attributes | |
|---|---|
idUUID |
The id of the snapshot |
namestring |
The name of the snapshot |
statestring |
The state of the snapshot |
intervalTypestring |
The interval type. MANUAL means that you created the snapshot manually (i.e. it's not a recurring snapshot) |
volumeIdUUID |
The id of the volume that was snapshotted |
volumestring |
The name of the volume that was snapshotted |
volumeTypestring |
The type of the volume that was snapshotted |
Create a snapshot
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-on/testing/snapshots?operation=create"
Request body example:
{
"volumeId": "4fe54594-a788-442c-b7a8-0237f7a4f70d",
"name": "BeforeUpgradeToV2",
"rapid": true
}
POST /services/:service_code/:environment_name/snapshots?operation=create
Create a snapshot of an existing volume. Note that the volume must be in its READY state to be able to take a snapshot of it. You can get a list of volumes using this API.
| Required | |
|---|---|
volumeIdUUID |
The id of the volume on which the snapshot is to be taken. |
| Optional | |
|---|---|
namestring |
A unique name to be given to the newly created snapshot. If this parameter is not provided then by default the concatenation of the instance name, volume name and the current timestamp is used. Eg: [instance.name]_[volume.name]_[timestamp] i-root-6E7_RapidVol_20190117153537 |
rapidboolean |
Indicates the location as to where the snapshot is supposed to be created. Setting this to true will ensure that the snapshot is created in the same primary storage as where the volume is. If false, then the snapshot is created in a secondary storage. |
Offerings
Offerings are what determine the characteristics of provisioned resources. There are 4 types of offerings : compute, disk, VPC and network offerings.
VPC offerings
VPC offerings determine which services are available to provisioned VPCs.
List VPC offerings
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/vpcofferings"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "41ac6ba0-6172-4bc4-bff6-b0831b91677c",
"name": "Default VPC offering",
"services": [
"PortForwarding",
"Vpn",
"SourceNat",
"Dhcp",
"NetworkACL",
"Dns",
"Lb",
"UserData",
"StaticNat"
],
"state": "Enabled"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/vpcofferings
Retrieve a list of available VPC offerings.
| Attributes | |
|---|---|
idUUID |
The id of the VPC offering |
namestring |
The name of the VPC offering |
servicesArray[string] |
The services provided by the offering |
statestring |
The state of the offering |
Retrieve a VPC offering
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/vpcofferings/41ac6ba0-6172-4bc4-bff6-b0831b91677c"
The above command returns a JSON structured like this:
{
"data": {
"id": "41ac6ba0-6172-4bc4-bff6-b0831b91677c",
"name": "Default VPC offering",
"services": [
"PortForwarding",
"Lb",
"NetworkACL",
"SourceNat",
"Dns",
"StaticNat",
"Vpn",
"Dhcp",
"UserData"
],
"state": "Enabled"
}
}
GET /services/:service_code/:environment_name/vpcofferings/:id
Retrieve a VPC offering.
| Attributes | |
|---|---|
idUUID |
The id of the VPC offering |
namestring |
The name of the VPC offering |
servicesArray[string] |
The services provided by the offering |
statestring |
The state of the offering |
Network offerings
Network offerings determine which services are available to each provisioned network.
List network offerings
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/networkofferings"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "89724d35-b69c-418c-be81-7d83fcfc9da9",
"name": "Load Balanced Tier",
"vpcOnly": true,
"services": [
"PortForwarding",
"Vpn",
"SourceNat",
"Dhcp",
"NetworkACL",
"Dns",
"Lb",
"UserData",
"StaticNat"
],
"state": "ENABLED"
},
{
"id": "087502ea-cb42-421b-9bd9-9cf9ae5d1b89",
"name": "Standard Tier",
"vpcOnly": true,
"services": [
"PortForwarding",
"Vpn",
"SourceNat",
"Dhcp",
"NetworkACL",
"Dns",
"UserData",
"StaticNat"
],
"state": "ENABLED"
},
{
"id": "0f1b9d72-b842-11e7-abc4-cec278b6b50a",
"name": "Isolated network",
"vpcOnly": false,
"services": [
"PortForwarding",
"SourceNat",
"Dhcp",
"Dns",
"UserData",
"StaticNat"
],
"state": "ENABLED"
}
],
"metadata": {
"recordCount": 3
}
}
GET /services/:service_code/:environment_name/networkofferings
Retrieve a list of available network offerings.
| Attributes | |
|---|---|
idUUID |
The id of the network offering |
namestring |
The name of the network offering |
vpcOnlyboolean |
Whether or not the offering is for VPC subnets |
servicesArray[string] |
The services provided by the offering |
statestring |
The state of the offering |
Retrieve a network offering
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/networkofferings/89724d35-b69c-418c-be81-7d83fcfc9da9"
The above command returns a JSON structured like this:
{
"data": {
"id": "89724d35-b69c-418c-be81-7d83fcfc9da9",
"name": "Load Balanced Tier",
"vpcOnly": true,
"services": [
"PortForwarding",
"Lb",
"NetworkACL",
"SourceNat",
"Dns",
"StaticNat",
"Vpn",
"Dhcp",
"UserData"
],
"state": "ENABLED"
}
}
GET /services/:service_code/:environment_name/networkofferings/:id
Retrieve a network offering.
| Attributes | |
|---|---|
idUUID |
The id of the network offering |
namestring |
The name of the network offering |
vpcOnlyboolean |
Whether or not the offering is for VPC subnets |
servicesArray[string] |
The services provided by the offering |
statestring |
The state of the offering |
Compute offerings
Compute offerings determine the number of vCPUs and the size of the memory allocated to new instances.
List compute offerings
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/computeofferings"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "40a2e5f7-22e6-4d1e-b03b-4a4b7c9cbc6f",
"name": "Custom CPU and memory",
"custom" : true,
"availableCpuCountValues": [1, 2, 4, 8],
"availableMemoryInMBValues": [1024, 2048, 4096, 8192],
"maxMemoryInMBToCpuRatio": 2048
},
{
"id": "1fb0caba-8ffb-4e77-8dcb-401170e15e0a",
"name": "1vCPU.1GB",
"cpuCount": 1,
"memoryInMB": 1024,
"custom" : false
},
{
"id": "37dabe14-1b7f-4f40-ab87-b3ab90c2e871",
"name": "32 CPU - 256 GB RAM",
"memoryInMB": 262144,
"cpuCount": 32,
"custom": false,
"type": "BareMetal",
"availabilityCount": 1
}
],
"metadata": {
"recordCount": 3
}
}
GET /services/:service_code/:environment_name/computeofferings
Retrieve a list of available compute offerings.
| Attributes | |
|---|---|
idUUID |
The id of the compute offering |
namestring |
The name of the compute offering |
availabilityCountinteger |
The number of compute offerings available to acquire. Only present for bare metal compute offerings. |
availableCpuCountValuesArray[integer] |
The list of valid cpu counts when used in the create instance operation. Only present for custom offerings |
availableMemoryInMBValuesArray[integer] |
The list of valid amounts of memory (in MB) that can be used in the create instance operation. Only present for custom offerings |
cpuCountint |
The number of vCPUs available to the created instance |
customboolean |
If true, the cpuCount and memoryInMB fields will be missing from the response and will be required on instance create |
maxMemoryInMBToCpuRatiointeger |
The maximum ratio of memory (in MB) to number of CPU of an instance created with this offering. Only present for custom offerings. |
memoryInMBint |
The amount of provisioned memory in MB |
typeenum |
The type of compute offering. Only present for bare metal compute offerings. Value is BareMetal. |
Retrieve a compute offering
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/computeofferings/40a2e5f7-22e6-4d1e-b03b-4a4b7c9cbc6f"
The above command returns a JSON structured like this:
{
"data": {
"id": "40a2e5f7-22e6-4d1e-b03b-4a4b7c9cbc6f",
"name": "1vCPU.512MB",
"cpuCount": 1,
"memoryInMB": 512,
"custom": false
}
}
GET /services/:service_code/:environment_name/computeofferings/:id
Retrieve a compute offering.
| Attributes | |
|---|---|
idUUID |
The id of the compute offering |
namestring |
The name of the compute offering |
availabilityCountinteger |
The number of compute offerings available to acquire. Only present for bare metal compute offerings. |
availableCpuCountValuesArray[integer] |
The list of valid cpu counts when used in the create instance operation. Only present for custom offerings |
availableMemoryInMBValuesArray[integer] |
The list of valid amounts of memory (in MB) that can be used in the create instance operation. Only present for custom offerings |
cpuCountint |
The number of vCPUs available to the created instance |
customboolean |
If true, the cpuCount and memoryInMB fields will be missing from the response and will be required on instance create |
maxMemoryInMBToCpuRatiointeger |
The maximum ratio of memory (in MB) to number of CPU of an instance created with this offering. Only present for custom offerings. |
memoryInMBint |
The amount of provisioned memory in MB |
typeenum |
The type of compute offering. Only present for bare metal compute offerings. Value is BareMetal. |
Disk offerings
Disk offerings determine the size and the performance (IOPS) of data volumes.
List disk offerings
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/diskofferings"
The above command returns a JSON structured like this:
{
"data": [
{
"customIops": false,
"customSize": false,
"gbSize": 20,
"id": "18bbab50-8d85-4b34-8361-0dc223ffd7e5",
"name": "20GB - 20 IOPS Min."
},
{
"customIops": false,
"customSize": false,
"gbSize": 50,
"id": "0432acc2-9226-4945-bf2e-9c8157be31d1",
"name": "50GB - 50 IOPS Min."
}
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/diskofferings
Retrieve a list of available disk offerings.
| Attributes | |
|---|---|
idUUID |
The id of the disk offering |
namestring |
The name of the disk offering |
gbSizeint |
The size of the data volume in GB |
customSizeboolean |
If the offering supports custom size |
customIopsboolean |
If the offering supports custom IOPS |
Retrieve a disk offering
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/diskofferings/18bbab50-8d85-4b34-8361-0dc223ffd7e5"
The above command returns a JSON structured like this:
{
"data": {
"customIops": false,
"customSize": false,
"gbSize": 20,
"id": "18bbab50-8d85-4b34-8361-0dc223ffd7e5",
"name": "20GB - 20 IOPS Min."
}
}
GET /services/:service_code/:environment_name/diskofferings/:id
Retrieve a disk offering.
| Attributes | |
|---|---|
idUUID |
The id of the disk offering |
namestring |
The name of the disk offering |
gbSizeint |
The size of the data volume in GB |
customSizeboolean |
If the offering supports custom size |
customIopsboolean |
If the offering supports custom IOPS |
Zones
Each zone consists of physically isolated hosts, storage, and networking infrastructure. Like deploying workloads across regions, deploying workloads over multiple zones can help ensure high availability of applications.
List zones
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/zones"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "ea901007-056b-4c50-bb3a-2dd635fce2ab",
"name": "ON-1"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/zones
Retrieve a list of available zones.
| Attributes | |
|---|---|
idUUID |
The id of the zone |
namestring |
The name of the zone |
Retrieve a zone
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-on/test_area/zones/ea901007-056b-4c50-bb3a-2dd635fce2ab"
The above command returns a JSON structured like this:
{
"data": {
"id": "ea901007-056b-4c50-bb3a-2dd635fce2ab",
"name": "ON-1"
}
}
GET /services/:service_code/:environment_name/zones/:id
Retrieve a zone
| Attributes | |
|---|---|
idUUID |
The id of the zone |
namestring |
The name of the zone |
OpenStack plugin
The CloudMC OpenStack plugin incorporates various OpenStack services such as Nova and Neutron into CloudMC's API. It also enforces CloudMC's environment-centric multi-tenancy model and RBAC over top of OpenStack.
Instances
Deploy and manage your instances. Instances are virtual machines or physical machines managed by OpenStack.
List instances
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/instances"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "30fca349-68b0-48c2-9ada-1f60f57fa44e",
"name": "nginx",
"cpuCount": 2,
"memoryInMB": 2048,
"state": "active",
"flavorId": "1d547941-1738-4d7b-a70b-b52a44ff18e5",
"flavorName": "2vCPU.2GB",
"imageId": "68f9027d-cf64-4648-a0fa-4667d5618b6b",
"imageName": "ubuntu",
"networkName": "web",
"privateIpAddress": "192.168.0.11",
"securityGroupNames": [
"webServerSecGroup",
"sshSecGroup"
],
"updatedDate": "2020-04-15 14:38:32",
"createdDate": "2020-04-15 14:37:53",
"addresses": [
{
"networkId": "738f3944-e44c-4729-9fca-c6ade9235850",
"networkName": "web",
"portId": "08e7fabd-33ad-400c-a973-7bbf8cff51bc",
"macAddress": "fa:16:3e:02:de:ae",
"ipAddress": "10.55.84.72",
"ipType": "fixed",
"ipVersion": 4
}
]
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/instances
Retrieve a list of all instances in an environment.
| Attributes | |
|---|---|
idUUID |
The id of the instance. |
namestring |
The name of the instance. |
statestring |
The current state of the instance. |
flavorIdUUID |
The flavor id of the instance. |
flavorNamestring |
The flavor name of the instance. |
imageIdUUID |
The image id of the instance. |
imageNamestring |
The image name of the instance. |
cpuCountint |
The number of vCPUs associated with the instance's flavor. |
memoryInMBint |
The number of megabytes associated with the instance's flavor. |
networkIdUUID |
The id of the network where instance is deployed. |
networkNamestring |
The name of the network where instance is deployed. |
privateIpAddressstring |
The instance's private IP address. |
securityGroupNamesArray[string] |
The list of security groups associated to the instance. |
createdDatestring |
The date the instance was created. |
updatedDatestring |
The date the instance was updated. |
addresses:Array[Object] |
The list of addresses attached to the instance. |
addresses.networkId:string |
The id of the network. |
addresses.networkName:string |
The name of the network. |
addresses.portId:string |
The id of the port. |
addresses.macAddress:string |
The MAC address associated to the address. |
addresses.ipAddress:string |
The IP address. |
addresses.ipType:string |
The type of address. Possible values : fixed, floating. |
addresses.ipVersion:integer |
The version of the IP protocol. |
Retrieve an instance
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/instances/30fca349-68b0-48c2-9ada-1f60f57fa44e"
The above command returns a JSON structured like this:
{
"data": {
"id": "30fca349-68b0-48c2-9ada-1f60f57fa44e",
"name": "nginx",
"cpuCount": 2,
"memoryInMB": 2048,
"state": "active",
"flavorId": "1d547941-1738-4d7b-a70b-b52a44ff18e5",
"flavorName": "2vCPU.2GB",
"imageId": "68f9027d-cf64-4648-a0fa-4667d5618b6b",
"imageName": "ubuntu",
"networkName": "web",
"privateIpAddress": "192.168.0.11",
"securityGroupNames": [
"webServerSecGroup",
"sshSecGroup"
],
"updatedDate": "2020-04-15 14:38:32",
"createdDate": "2020-04-15 14:37:53",
"addresses": [
{
"networkId": "738f3944-e44c-4729-9fca-c6ade9235850",
"networkName": "web",
"portId": "08e7fabd-33ad-400c-a973-7bbf8cff51bc",
"macAddress": "fa:16:3e:02:de:ae",
"ipAddress": "10.55.84.72",
"ipType": "fixed",
"ipVersion": 4
}
]
}
}
GET /services/:service_code/:environment_name/instances/:id
Retrieve information about an instance.
| Attributes | |
|---|---|
idUUID |
The id of the instance. |
namestring |
The name of the instance. |
statestring |
The current state of the instance. |
flavorIdUUID |
The flavor id of the instance. |
flavorNamestring |
The flavor name of the instance. |
imageIdUUID |
The image id of the instance. |
imageNamestring |
The image name of the instance. |
cpuCountint |
The number of vCPUs associated with the instance's flavor. |
memoryInMBint |
The number of megabytes associated with the instance's flavor. |
networkIdUUID |
The id of the network where instance is deployed. |
networkNamestring |
The name of the network where instance is deployed. |
privateIpAddressstring |
The instance's private IP address. |
securityGroupNamesArray[string] |
The list of security groups associated to the instance. |
createdDatestring |
The date the instance was created. |
updatedDatestring |
The date the instance was updated. |
addresses:Array[Object] |
The list of addresses attached to the instance. |
addresses.networkId:string |
The id of the network. |
addresses.networkName:string |
The name of the network. |
addresses.portId:string |
The id of the port. |
addresses.macAddress:string |
The MAC address associated to the address. |
addresses.ipAddress:string |
The IP address. |
addresses.ipType:string |
The type of address. Possible values : fixed, floating. |
addresses.ipVersion:integer |
The version of the IP protocol. |
Create an instance
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/instances"
Request body example:
{
"name": "web1",
"imageId": "1d547941-1738-4d7b-a70b-b52a44ff18e5",
"flavorId": "68f9027d-cf64-4648-a0fa-4667d5618b6b",
"networkId": "2fc5a74b-26c9-4541-af3f-84ee4c75eb0c",
"securityGroupNames": ["secGroupA", "secGroupB"]
}
POST /services/:service_code/:environment_name/instances
Create an instance in an environment.
| Required | |
|---|---|
imageIdUUID |
The image to use for this instance. |
flavorIdUUID |
The flavor will determine the number of CPU and RAM of your instance. |
networkIdUUID |
The network in which the instance will be created. If you don't have a network, it can be created through the create network API. |
securityGroupNamesArray[string] |
The list of security groups to be associated to the instance. |
| Optional | |
|---|---|
namestring |
Name of the instance. |
userDatastring |
Data that the user can specify when they launch an instance. User data can be used in the cloud-init system as a script that is run during the initial launch. The user data field can be used to configure SSH keys, user settings, or run a script. |
sshKeyNamestring |
Name of the ssh key to link to the instance. |
volumeToAttachObject |
Specifies that a volume must be attached a volume needs to be attached to the instance. |
volumeToAttach.idObject |
Id of an existing volume to attach to the instance. |
volumeToAttach.sizeInGBObject |
The size in GB of the new disk to attached to the instance. |
Associate a floating IP
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/instances/30fca349-68b0-48c2-9ada-1f60f57fa44e?operation=associate"
Request body example:
{
"floatingIpId": "287a3963-983b-4602-9dea-4dff89e9dc10"
}
POST /services/:service_code/:environment_name/instances/:id?operation=associate
Associate a floating IP to an instance in your environment.
| Required | Description |
|---|---|
floatingIpIdUUID |
The ID of a previously-acquired floating IP. |
Change security groups
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/instances/30fca349-68b0-48c2-9ada-1f60f57fa44e?operation=changeSecurityGroups"
Request body example:
{
"securityGroupNames": [ "securityGroupNameA", "securityGroupNameB"]
}
POST /services/:service_code/:environment_name/instances/:id?operation=changeSecurityGroups
Change the security groups of an instance to the ones specified in the request.
| Required | Description |
|---|---|
securityGroupNamesArray[string] |
A list of security group names that should be associated to the instance |
Delete an instance
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/instances/30fca349-68b0-48c2-9ada-1f60f57fa44e"
DELETE /services/:service_code/:environment_name/instances/:id
Delete an instance.
Networks
Networks are provisioned to be able to control data flow to instances. To communicate with the external network, the network must be connected to a router.
List networks
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/networks"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "a9e8861d-64a1-4126-b385-6e4db9a5814f",
"name": "default",
"enabled": true,
"external": false,
"gateway": "10.55.84.1",
"cidr": "10.55.84.0/22",
"dhcpEnabled":true,
"ipVersion": "V4",
"subnetId": "bda27442-f6c8-4033-84f0-ffcf319228a4"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/networks
Retrieve a list of all networks in an environment.
| Attribute | Description |
|---|---|
idUUID |
The network's id. |
namestring |
The network's name. |
enabledboolean |
If the network is enabled. |
externalboolean |
If the network is accessible from the external. |
gatewaystring |
The IP of the gateway. |
cidrstring |
CIDR of the network. |
dhcpEnabledboolean |
If DHCP is handled by the network. |
ipVersionstring |
V4 or V6. |
subnetIdstring |
The id of the OpenStack subnet it maps to. |
Retrieve a network
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/networks/a9e8861d-64a1-4126-b385-6e4db9a5814f"
The above command returns a JSON structured like this:
{
"data": {
"id": "a9e8861d-64a1-4126-b385-6e4db9a5814f",
"name": "default",
"enabled": true,
"external": false,
"gateway": "10.55.84.1",
"cidr": "10.55.84.0/22",
"dhcpEnabled":true,
"ipVersion": "V4",
"subnetId": "bda27442-f6c8-4033-84f0-ffcf319228a4"
}
}
GET /services/:service_code/:environment_name/networks/:id
Retrieve information about a network.
| Attribute | Description |
|---|---|
idUUID |
The network's id. |
namestring |
The network's name. |
enabledboolean |
If the network is enabled. |
externalboolean |
If the network is accessible from the external. |
gatewaystring |
The IP of the gateway. |
cidrstring |
CIDR of the network. |
dhcpEnabledboolean |
If DHCP is handled by the network. |
ipVersionstring |
V4 or V6. |
subnetIdstring |
The id of the OpenStack subnet it maps to. |
Create a network
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/networks"
Request body example:
{
"name": "web",
"cidr": "10.50.0.0/22",
"dhcpEnabled":true
}
POST /services/:service_code/:environment_name/networks
Create a network in an environment.
| Optional | |
|---|---|
namestring |
Name of the network |
cidrstring |
The CIDR of the network. The mask should be between 1 and 30 inclusively. Example: 10.50.0.0/22 |
dhcpEnabledboolean |
If DHCP should be enabled for the network or if it will be handled by the user |
routerIdstring |
The id of an existing router. If provided, it will create an interface on that router for the created network. It may not be provided with externalNetworkId |
externalNetworkIdstring |
The id of the external network. If provided, it will create a router connected to that external network and add an interface on that router for the created network. It may not be provided with routerId |
N.B.: The name and cidr will be autogenerated if left blank. dhcpEnabled will default to false
Delete a network
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/networks/a9e8861d-64a1-4126-b385-6e4db9a5814f"
DELETE /services/:service_code/:environment_name/networks/:id
Delete a network.
Flavors
Flavors are available hardware configurations for instances. They store the information for compute and memory capacity.
List flavors
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/flavors"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "1d547941-1738-4d7b-a70b-b52a44ff18e5",
"name": "1vCPU.256MB",
"ephemeralSizeInGB": 0,
"diskSizeInGB": 20,
"memorySizeInMB": 256,
"cpuCount": 1
},
{
"id": "921e8296-c801-498c-90a9-4398cd44681f",
"name": "1vCPU.512MB",
"ephemeralSizeInGB": 0,
"diskSizeInGB": 20,
"memorySizeInMB": 512,
"cpuCount": 1
}
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/flavors
Retrieve a list of available flavors.
| Attributes | |
|---|---|
idUUID |
The flavor's id. |
namestring |
The flavor name. |
ephemeralSizeInGBstring |
The size of the ephemeral disk in GB. |
diskSizeInGBstring |
The size of the root disk in GB. |
memorySizeInMBstring |
The size of the memory in MB. |
cpuCountstring |
The number of vCPU assigned. |
Retrieve a flavor
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/flavors/1d547941-1738-4d7b-a70b-b52a44ff18e5"
The above command returns a JSON structured like this:
{
"data": {
"id": "1d547941-1738-4d7b-a70b-b52a44ff18e5",
"name": "1vCPU.256MB",
"ephemeralSizeInGB": 0,
"diskSizeInGB": 20,
"memorySizeInMB": 256,
"cpuCount": 1
}
}
GET /services/:service_code/:environment_name/flavors/:id
Retrieve information about a flavor.
| Attributes | |
|---|---|
idUUID |
The flavor's id. |
namestring |
The flavor name. |
ephemeralSizeInGBstring |
The size of the ephemeral disk in GB. |
diskSizeInGBstring |
The size of the root disk in GB. |
memorySizeInMBstring |
The size of the memory in MB. |
cpuCountstring |
The number of vCPU assigned. |
Images
Images are virtual machine images that have a virtual disk that contains a bootable operating system.
List images
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/images"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "22f53310-798d-4029-bb00-747a52d2a376",
"name": "ubuntu"
},
{
"id": "68f9027d-cf64-4648-a0fa-4667d5618b6b",
"name": "centos7"
}
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/images
Retrieve a list of available images.
| Attributes | |
|---|---|
idUUID |
The image's id. |
namestring |
The image name. |
Retrieve an image
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/images/22f53310-798d-4029-bb00-747a52d2a376"
The above command returns a JSON structured like this:
{
"data": {
"id": "22f53310-798d-4029-bb00-747a52d2a376",
"name": "ubuntu"
}
}
GET /services/:service_code/:environment_name/images/:id
Retrieve information about an image.
| Attributes | |
|---|---|
idUUID |
The image's id. |
namestring |
The image name. |
Floating IPs
Floating IPs are public IP addresses that a user can acquire and use in an environment.
List floating IPs
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/floatingips"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "287a3963-983b-4602-9dea-4dff89e9dc10",
"floatingIpAddress": "10.182.56.27",
"fixedIpAddress": "10.0.0.8",
"externalNetworkId": "963b6966-d9d7-48a8-8141-f414a809dbf4"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/floatingips
Retrieve a list of all floating IPs in an environment.
| Attributes | |
|---|---|
idUUID |
The floating IP's id. |
floatingIpAddressstring |
The floating IP's public IP address. |
fixedIpAddressstring |
The fixed IP to which the floating IP is associated. This may be empty if the floating IP is not associated with an instance. |
externalNetworkIdUUID |
The id of the external network to which the floating IP belongs. |
Retrieve a floating IP
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/floatingips/287a3963-983b-4602-9dea-4dff89e9dc10"
The above command returns a JSON structured like this:
{
"data": {
"id": "287a3963-983b-4602-9dea-4dff89e9dc10",
"floatingIpAddress": "10.182.56.27",
"fixedIpAddress": "10.0.0.8",
"externalNetworkId": "963b6966-d9d7-48a8-8141-f414a809dbf4"
}
}
GET /services/:service_code/:environment_name/floatingips/:id
Retrieve information about a floating IP.
| Attributes | |
|---|---|
idUUID |
The floating IP's id. |
floatingIpAddressstring |
The floating IP's public IP address. |
fixedIpAddressstring |
The fixed IP to which the floating IP is associated. This may be empty if the floating IP is not associated with an instance. |
externalNetworkIdUUID |
The id of the external network to which the floating IP belongs. |
Acquire a floating IP
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/floatingips"
Request body example:
{
"externalNetworkId": "networkId",
}
POST /services/:service_code/:environment_name/floatingips
Acquire a floating IP in an environment.
| Optional | |
|---|---|
externalNetworkIdstring |
The external network id to associate the new floating ip. If there is more than one network, it will be required to specify it. |
Release a floating IP
curl -X DELETE \
-H "MC-Api-Key: your_api_key"
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/floatingips/287a3963-983b-4602-9dea-4dff89e9dc10"
DELETE /services/:service_code/:environment_name/floatingips/:id
Release a floating IP.
Security groups
Security groups manage network access to instances.
List security groups
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/securitygroups"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "1bd672f4-b274-4371-a792-b0a6c6778cc7",
"name": "default",
"description": "Default security group",
"isDefault": true
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/securitygroups
Retrieve a list of all security groups in an environment.
| Attribute | Description |
|---|---|
idUUID |
The security group's id. |
namestring |
The security group's name. |
descriptionstring |
A description of the group's purpose. |
isDefaultboolean |
If the security group is the default. |
Retrieve a security group
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/securitygroups/1bd672f4-b274-4371-a792-b0a6c6778cc7"
The above command returns a JSON structured like this:
{
"data": {
"id": "1bd672f4-b274-4371-a792-b0a6c6778cc7",
"name": "default",
"description": "Default security group",
"isDefault": true
}
}
GET /services/:service_code/:environment_name/securitygroups/:id
Retrieve information about a security group.
| Attribute | Description |
|---|---|
idUUID |
The security group's id. |
namestring |
The security group's name. |
descriptionstring |
A description of the group's purpose. |
isDefaultboolean |
If the security group is the default. |
Create a security group
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/securitygroups"
Request body example:
{
"name": "security-group-1",
"description": "My very first security group"
}
POST /services/:service_code/:environment_name/securitygroups
Create a security group in an environment.
| Required | Description |
|---|---|
namestring |
The security group's name. |
descriptionstring |
A description of the group's purpose. |
Delete a security group
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/securitygroups/1bd672f4-b274-4371-a792-b0a6c6778cc7"
DELETE /services/:service_code/:environment_name/securitygroups/:id
Delete a security group.
Security group rules
Security group rules define the type of traffic that can access the instances associated with a security group.
List security group rules within a security group
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/securitygrouprules?securitygroupid=f54f050b-01b2-4a73-b6e1-4e13a5566323"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "655d3bcb-3f8a-4738-b50a-53bca43469b5",
"remoteAddress": "0.0.0.0/0",
"startPort": 1,
"endPort": 65535,
"etherType": "IPv4",
"protocol": "UDP",
"ingress": true,
"securityGroupId": "f54f050b-01b2-4a73-b6e1-4e13a5566323"
},
{
"id": "8d92b22b-b7d2-4584-865d-a9929cb1a24c",
"remoteAddress": "0.0.0.0/0",
"startPort": 15,
"endPort": 30,
"etherType": "IPv4",
"protocol": "TCP",
"ingress": true,
"securityGroupId": "f54f050b-01b2-4a73-b6e1-4e13a5566323"
}
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/securitygrouprules?securitygroupid=:securityGroupId
Retrieve a list of all security group rules in a security group.
| Attribute | Description |
|---|---|
idUUID |
The security group rule's id. |
remoteAddressstring |
Remote IPs or CIDRs associated with this rule. |
startPortint |
Minimum port that is matched by this rule. |
endPortint |
Maximum port that is matched by this rule. |
etherTypestring |
IP type, either IPv4 or IPv6. |
protocolstring |
The IP protocol, either ICMP, TCP or UDP. |
ingressboolean |
Direction in which the rule is applied, false implies egress. |
securityGroupIdUUID |
The ID of the parent security group. |
Retrieve a security group rule
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/securitygrouprules/655d3bcb-3f8a-4738-b50a-53bca43469b5"
The above command returns a JSON structured like this:
{
"data": {
"id": "655d3bcb-3f8a-4738-b50a-53bca43469b5",
"remoteAddress": "0.0.0.0/0",
"startPort": 1,
"endPort": 65535,
"etherType": "IPv4",
"protocol": "ICMP",
"ingress": true,
"securityGroupId": "f54f050b-01b2-4a73-b6e1-4e13a5566323"
}
}
GET /services/:service_code/:environment_name/securitygrouprules/:id
Retrieve information about a security group rule.
| Attribute | Description |
|---|---|
idUUID |
The security group rule's id. |
remoteAddressstring |
Remote IPs or CIDRs associated with this rule. |
startPortint |
Minimum port that is matched by this rule. |
endPortint |
Maximum port that is matched by this rule. |
etherTypestring |
IP type, either IPv4 or IPv6. |
protocolstring |
The IP protocol, either ICMP, TCP or UDP. |
ingressboolean |
Direction in which the rule is applied, false implies egress. |
securityGroupIdUUID |
The ID of the parent security group. |
Create a security group rule
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/securitygrouprules"
Request body example:
{
"ingress": true,
"protocol": "UDP",
"startPort": 10,
"endPort": 20,
"remoteAddress": "0.0.0.0/0",
"securityGroupId": "f54f050b-01b2-4a73-b6e1-4e13a5566323",
}
POST /services/:service_code/:environment_name/securitygrouprules
Create a security group rule for a security group.
| Required | Description |
|---|---|
securityGroupIdUUID |
The ID of the parent security group. |
| Optional | Description |
|---|---|
ingressboolean |
Direction in which the rule is applied, false implies egress. Defaults to ingress. |
protocolstring |
The IP protocol, either ICMP, TCP or UDP. Defaults to allow all protocols. |
startPortint |
Minimum port that is matched by this rule, required if end port specified. Defaults to 1. |
endPortint |
Maximum port that is matched by this rule. Defaults to 65535. |
remoteAddressstring |
Remote IPs or CIDRs associated with this rule. Defaults to allow all IPs. |
Delete a security group rule
curl -X DELETE \
-H "MC-Api-Key: your_api_key"
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/securitygrouprules/655d3bcb-3f8a-4738-b50a-53bca43469b5"
DELETE /services/:service_code/:environment_name/securitygrouprules/:id
Delete a security group rule.
Routers
Routers route traffic between networks, including the public internet.
List routers
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/routers"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "212eb8d8-80ee-4edd-8bae-1efed8bc5c71",
"name": "external-router",
"externalNetworkId": "167bea1e-f15a-41bd-8d54-44b613bfa36c",
"externalNetworkName": "public-net",
"networkNames": [
"web",
"data"
],
"networkIds": [
"4beaf851-c0d8-4ab7-9003-3b7c0e59f3d9",
"68f97fb0-6a71-4be1-87bf-1c805940d2cb"
]
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/routers
Retrieve a list of routers in an OpenStack environment.
| Attributes | Description |
|---|---|
idUUID |
The router's ID. |
namestring |
The router's name. |
networkIdsArray[UUID] |
The router's internal network IDs. |
networkNamesArray[string] |
The router's internal network names. |
externalNetworkIdUUID |
The router's external network ID. |
externalNetworkNamestring |
The router's external network name. |
Retrieve a router
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/routers/212eb8d8-80ee-4edd-8bae-1efed8bc5c71"
The above command returns a JSON structured like this:
{
"data": {
"id": "212eb8d8-80ee-4edd-8bae-1efed8bc5c71",
"name": "external-router",
"externalNetworkId": "167bea1e-f15a-41bd-8d54-44b613bfa36c",
"externalNetworkName": "public-net",
"networkNames": [
"web",
"data"
],
"networkIds": [
"4beaf851-c0d8-4ab7-9003-3b7c0e59f3d9",
"68f97fb0-6a71-4be1-87bf-1c805940d2cb"
]
}
}
GET /services/:service_code/:environment_name/routers/:id
Retrieve a single router in an OpenStack environment.
| Attributes | Description |
|---|---|
idUUID |
The router's ID. |
namestring |
The router's name. |
networkIdsArray[UUID] |
The router's internal network IDs. |
networkNamesArray[string] |
The router's internal network names. |
externalNetworkIdUUID |
The router's external network ID. |
externalNetworkNamestring |
The router's external network name. |
Create a router
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/routers"
Request body example:
{
"name": "external-router",
"externalNetworkId": "167bea1e-f15a-41bd-8d54-44b613bfa36c"
}
POST /services/:service_code/:environment_name/routers
Create a router.
| Attributes | Description |
|---|---|
namestring |
The router's name. |
externalNetworkIdUUID |
The router's external network ID. |
Add a router interface
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/routers/212eb8d8-80ee-4edd-8bae-1efed8bc5c71?operation=addRouterInterface"
Request body example:
{
"networkId": "471eb361-c028-45f5-bd1a-6d05a057624f",
}
POST /services/:service_code/:environment_name/routers/:id?operation=addRouterInterface
Connect a router to a network.
| Attributes | Description |
|---|---|
networkIdUUID |
The ID of the network to connect. |
Delete a router
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/routers/212eb8d8-80ee-4edd-8bae-1efed8bc5c71"
DELETE /services/:service_code/:environment_name/routers/:id
Delete a router.
Router interfaces
Router interfaces connect a router to a network.
List router interfaces
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/routerinterfaces?routerid=3de4f523-06ce-4955-acb0-b8e3d61ec582"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "b5f0cbbf-45f3-4e77-8a5c-90351f83e5f9",
"networkName": "test2",
"networkId": "d507486c-eacb-48ff-841e-e3938213d95f",
"portId": "b5f0cbbf-45f3-4e77-8a5c-90351f83e5f9",
"privateIp": "10.182.15.1",
"routerId": "3de4f523-06ce-4955-acb0-b8e3d61ec582",
"routerName": "routeName1"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/routerinterfaces?routerid=:routerid
Retrieve a list of router interfaces associated with a router in an OpenStack environment.
| Attributes | Description |
|---|---|
idUUID |
The router interface's ID. |
networkNamestring |
The name of the connected network. |
networkIdUUID |
The ID of the connected network. |
portIdUUID |
The ID of the port the interface is connected to (same as interface ID). |
privateIpstring |
The private IP of the router interface. |
routerIdUUID |
The ID of the parent router. |
routerNameUUID |
The name of the parent router. |
Retrieve a router interface
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/routerinterfaces/b5f0cbbf-45f3-4e77-8a5c-90351f83e5f9"
The above command returns a JSON structured like this:
{
"data": {
"id": "b5f0cbbf-45f3-4e77-8a5c-90351f83e5f9",
"networkName": "test2",
"networkId": "d507486c-eacb-48ff-841e-e3938213d95f",
"portId": "b5f0cbbf-45f3-4e77-8a5c-90351f83e5f9",
"privateIp": "10.182.15.1",
"routerId": "3de4f523-06ce-4955-acb0-b8e3d61ec582",
"routerName": "routeName1"
}
}
GET /services/:service_code/:environment_name/routerinterfaces/:id
Retrieve a single router interface in an OpenStack environment.
| Attributes | Description |
|---|---|
idUUID |
The router interface's ID. |
networkNamestring |
The name of the connected network. |
networkIdUUID |
The ID of the connected network. |
portIdUUID |
The ID of the port the interface is connected to (same as interface ID). |
privateIpstring |
The private IP of the router interface. |
routerIdUUID |
The ID of the parent router. |
routerNameUUID |
The name of the parent router. |
Create a router interface
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/routerinterfaces"
Request body example:
{
"networkId": "d507486c-eacb-48ff-841e-e3938213d95f",
"routerId": "3de4f523-06ce-4955-acb0-b8e3d61ec582"
}
POST /services/:service_code/:environment_name/routerinterfaces
Create a router interface.
| Required | Description |
|---|---|
networkIdUUID |
The ID of the network that is being connected. |
routerIdUUID |
The ID of the router. |
Delete a router interface
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/routerinterfaces/c14ed06b-6de9-4b3e-aac9-9e6c1406de9e"
DELETE /services/:service_code/:environment_name/routerinterfaces/:id
Delete a router interface.
SSH keys
SSH keys can be assigned on instance creation to provide SSH access.
List SSH keys
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/sshkeys"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "ssh-key-a",
"name": "ssh-key-a",
"fingerprint": "17:43:84:aa:a1:ed:6b:aa:10:be:73:1f:63:d0:53:16",
"publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDlf6/L7kuWWyo8y718JXeKKJa5kdT5QT0GcJUVvuLGNAf/Xjwhc9ThaQk+5mBs49hECTTYlOP0J5lb69kpU2fCmRzroazMD8isOh33o7HdNT9F2CWEKCHJ4Qhd40bXf3b4twz43HIo/pkPyJZ7OVC1v39UNvSkh+iNdUkCVZAO9ijAeW4n+F6WSKG1GqZrdElGSMpTM/DMmNo393N3xOcW4Z9qjG7PGdPIgtxqM/wmyyv0id5eV/QkciOaVEgJ7jzQ/iQA1rdEPI7EojLFgaNTIRjp/fQ/BPQ47ZKimwRzns1csupr2BENDpAXqAqHTgSpEyeG/5OvD4oA521fLoiv Generated-by-Nova"
},
{
"id": "ssh-key-b",
"name": "ssh-key-b",
"fingerprint": "2b:36:6b:f7:98:ef:6a:32:bf:c8:19:94:80:c1:44:60",
"publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCnZh9CoR97SY2gA7/JhShzNcxt0VVEi0QMOH/IJZWdu5mtSdJrIvZVTMVVKdae6PUQaYsVt5IImeOZLYiHkUNvvkm291BnKwuymjV9J/CftRs0ZM0X/VhftmROAT5G89Fw57VU6L6bjV4ex7fvAAhr44KJZsgViswOcxJSuwoGmQX15GJAxsSOQ4GthHWJWoifBG0la7+rtAPRUS/qAcCcVuaLNqTalSUtrAytD8J4tswd6UzzPf3MUJWMW36aExwhJW22oHQxvOSot2e36ZFhtHXj1PJs4ZG9mE9JMMz/Y9eIdHMg30vb/YQ5ftsJUs9xjjDD5+fjQxttB1QqqyCp Generated-by-Nova"
}
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/sshkeys
Retrieve a list of SSH keys in an OpenStack domain.
| Attributes | Description |
|---|---|
idstring |
The SSH key's ID which takes the same value as the name. |
namestring |
The SSH key's name. |
fingerprintstring |
A short sequence of bytes used to identify the SSH key. |
publicKeystring |
The SSH public key. |
Retrieve a SSH key
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/sshkeys/ssh-key-a"
The above command returns a JSON structured like this:
{
"data": {
"id": "ssh-key-a",
"name": "ssh-key-a",
"fingerprint": "17:43:84:aa:a1:ed:6b:aa:10:be:73:1f:63:d0:53:16",
"createDate": "2017-06-19T16:19:48.000Z",
"publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDlf6/L7kuWWyo8y718JXeKKJa5kdT5QT0GcJUVvuLGNAf/Xjwhc9ThaQk+5mBs49hECTTYlOP0J5lb69kpU2fCmRzroazMD8isOh33o7HdNT9F2CWEKCHJ4Qhd40bXf3b4twz43HIo/pkPyJZ7OVC1v39UNvSkh+iNdUkCVZAO9ijAeW4n+F6WSKG1GqZrdElGSMpTM/DMmNo393N3xOcW4Z9qjG7PGdPIgtxqM/wmyyv0id5eV/QkciOaVEgJ7jzQ/iQA1rdEPI7EojLFgaNTIRjp/fQ/BPQ47ZKimwRzns1csupr2BENDpAXqAqHTgSpEyeG/5OvD4oA521fLoiv Generated-by-Nova"
}
}
GET /services/:service_code/:environment_name/sshkeys/:id
Retrieve a single SSH key in an OpenStack domain.
| Attributes | Description |
|---|---|
idstring |
The SSH key's ID which takes the same value as the name. |
namestring |
The SSH key's name. |
fingerprintstring |
A short sequence of bytes used to identify the SSH key. |
createDate date |
The date the SSH key was created. |
publicKeystring |
The SSH public key. |
Create a SSH key
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/sshkeys"
Request body example:
{
"name": "ssh-key-c",
"publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDlf6/L7kuWWyo8y718JXeKKJa5kdT5QT0GcJUVvuLGNAf/Xjwhc9ThaQk+5mBs49hECTTYlOP0J5lb69kpU2fCmRzroazMD8isOh33o7HdNT9F2CWEKCHJ4Qhd40bXf3b4twz43HIo/pkPyJZ7OVC1v39UNvSkh+iNdUkCVZAO9ijAeW4n+F6WSKG1GqZrdElGSMpTM/DMmNo393N3xOcW4Z9qjG7PGdPIgtxqM/wmyyv0id5eV/QkciOaVEgJ7jzQ/iQA1rdEPI7EojLFgaNTIRjp/fQ/BPQ47ZKimwRzns1csupr2BENDpAXqAqHTgSpEyeG/5OvD4oA521fLoiv Generated-by-Nova"
}
POST /services/:service_code/:environment_name/sshkeys
Create a SSH key.
| Required | Description |
|---|---|
namestring |
The SSH key's name. |
publicKeystring |
A public SSH key in RSA format. |
Delete a SSH key
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/sshkeys/ssh-key-c"
DELETE /services/:service_code/:environment_name/sshkeys/:name
Delete a SSH key.
Volumes
Volumes are block-level storage devices that can be attached to instances.
List volumes
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/volumes"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "52cfc2f8-5b1f-4833-83cd-a77f55c5ed24",
"name": "web-data",
"description": "Storage for the web server",
"state": "available",
"sizeInGB": 50
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/volumes
Retrieve a list of volumes.
| Attributes | |
|---|---|
idUUID |
The volume's id. |
namestring |
The volume name. |
descriptionstring |
The volume's description. |
sizeInGBinteger |
The volume's size in GB. |
statestring |
The volume's state. |
instanceIdstring |
The instance id to which the volume is attached. |
instanceNamestring |
The instance name to which the volume is attached. |
devicestring |
The device under which the volume is The volume's state. |
Retrieve a volume
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/volumes/52cfc2f8-5b1f-4833-83cd-a77f55c5ed24"
The above command returns a JSON structured like this:
{
"data": {
"id": "52cfc2f8-5b1f-4833-83cd-a77f55c5ed24",
"name": "web-data",
"description": "Storage for the web server",
"state": "available",
"sizeInGB": 50
}
}
GET /services/:service_code/:environment_name/volumes/:id
Retrieve a volume.
| Attributes | |
|---|---|
idUUID |
The volume's id. |
namestring |
The volume name. |
descriptionstring |
The volume's description. |
sizeInGBinteger |
The volume's size in GB. |
statestring |
The volume's state. |
instanceIdstring |
The instance id to which the volume is attached. |
instanceNamestring |
The instance name to which the volume is attached. |
devicestring |
The device under which the volume is The volume's state. |
Create a volume
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/volumes"
Request body example:
{
"name": "mysql",
"description": "Production MySQL data",
"sizeInGB":20
}
POST /services/:service_code/:environment_name/volumes
Create a volume.
| Required | Description |
|---|---|
namestring |
The volume name. |
descriptionstring |
The volume description. |
sizeInGBinteger |
The volume's size in GB. |
Delete a volume
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/volumes/52cfc2f8-5b1f-4833-83cd-a77f55c5ed24"
DELETE /services/:service_code/:environment_name/volumes/:id
Delete a volume.
Attach a volume to an instance
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/volumes/52cfc2f8-5b1f-4833-83cd-a77f55c5ed24?operation=attach"
Request body example:
{
"instanceId": "449efafc-0a6f-4f9e-9602-4b9ac2400abd"
}
POST /services/:service_code/:environment_name/volumes/:id?operation=attach
Attach a volume to an instance.
| Required | Description |
|---|---|
instanceIdUUID |
The instance id. |
Detach a volume from an instance
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/volumes/52cfc2f8-5b1f-4833-83cd-a77f55c5ed24?operation=detach"
POST /services/:service_code/:environment_name/volumes/:id?operation=detach
Detach a volume from an instance.
Extend a volume
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/volumes/52cfc2f8-5b1f-4833-83cd-a77f55c5ed24?operation=extend"
Request body example:
{
"sizeInGB": 40
}
POST /services/:service_code/:environment_name/volumes/:id?operation=extend
Extend a volume size.
| Required | Description |
|---|---|
sizeInGBinteger |
The new size of the volume. It must be greater than the existing size. |
Take a snapshot of a volume
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-H "Content-Type: application/json" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/volumes/52cfc2f8-5b1f-4833-83cd-a77f55c5ed24?operation=snapshot"
POST /services/:service_code/:environment_name/volumes/:id?operation=snapshot
Generate a snapshot of the volume.
Snapshots
Snapshots are point in time copies of volumes that can be used to create other volumes.
List Snapshots
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/snapshots"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "4b41c7de-b2a8-4cb7-82ce-46685b07921d",
"name": "s-web-data-CJ6",
"volumeId": "52cfc2f8-5b1f-4833-83cd-a77f55c5ed24",
"volumeName": "web-data",
"sizeInGB": 50,
"state": "available"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/snapshots
Retrieve a list of snapshots.
| Attributes | |
|---|---|
idUUID |
The snapshot's id. |
namestring |
The snapshot name. |
volumeIdUUID |
The volume's id. |
volumeNamestring |
The volume's name. |
sizeInGBinteger |
The snapshot's size in GB. |
statestring |
The snapshot's state. |
Retrieve a snapshot
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/snapshots/4b41c7de-b2a8-4cb7-82ce-46685b07921d"
The above command returns a JSON structured like this:
{
"data": {
"id": "4b41c7de-b2a8-4cb7-82ce-46685b07921d",
"name": "s-web-data-CJ6",
"volumeId": "52cfc2f8-5b1f-4833-83cd-a77f55c5ed24",
"volumeName": "web-data",
"sizeInGB": 50,
"state": "available"
}
}
GET /services/:service_code/:environment_name/snapshots/:id
Retrieve information about a snapshot.
| Attributes | |
|---|---|
idUUID |
The snapshot's id. |
namestring |
The snapshot name. |
volumeIdUUID |
The volume's id. |
volumeNamestring |
The volume's name. |
sizeInGBinteger |
The snapshot's size in GB. |
statestring |
The snapshot's state. |
Delete a snapshot
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/compute-os/devel/snapshots/4b41c7de-b2a8-4cb7-82ce-46685b07921d"
DELETE /services/:service_code/:environment_name/snapshots/:id
Delete a snapshot.
Google Cloud Platform plugin
The Google Cloud Platform plugin provides endpoints for carrying out operations on CloudMC compute and networking entities. It also enforces CloudMC's environment-centric multi-tenancy model and RBAC over top of GCP.
Compute
Instances
Deploy and manage your instances.
List instances
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/instances"
The above command returns a JSON structured like this:
{
"data": [
{
"status": "RUNNING",
"zone": "https://www.googleapis.com/compute/v1/projects/test-area-oox/zones/northamerica-northeast1-a",
"machineType": "https://www.googleapis.com/compute/v1/projects/test-area-oox/zones/northamerica-northeast1-a/machineTypes/f1-micro",
"cpuPlatform": "Intel Skylake",
"creationTimestamp": "2019-04-19T12:12:30.756-07:00",
"deletionProtection": false,
"disks": [
{
"autoDelete": true,
"boot": true,
"deviceName": "i-test-kkn",
"guestOsFeatures": [
{
"type": "VIRTIO_SCSI_MULTIQUEUE"
}
],
"index": 0,
"interface": "SCSI",
"kind": "compute#attachedDisk",
"licenses": [
"https://www.googleapis.com/compute/v1/projects/debian-cloud/global/licenses/debian-9-stretch"
],
"mode": "READ_WRITE",
"source": "https://www.googleapis.com/compute/v1/projects/test-area-oox/zones/northamerica-northeast1-a/disks/i-test-kkn",
"type": "PERSISTENT"
}
],
"kind": "compute#instance",
"labelFingerprint": "42WmSpB8rSM=",
"metadata": {
"fingerprint": "RnfaWQ2UP4U=",
"items": [
{
"key": "startup-script",
"value": "#! /bin/bash\napt-get update\nEOF"
}
],
"kind": "compute#metadata"
},
"networkInterfaces": [
{
"accessConfigs": [
{
"kind": "compute#accessConfig",
"name": "external-nat",
"natIP": "35.203.99.102",
"networkTier": "PREMIUM",
"type": "ONE_TO_ONE_NAT"
}
],
"fingerprint": "NG6-4Cdf0KA=",
"kind": "compute#networkInterface",
"name": "nic0",
"network": "https://www.googleapis.com/compute/v1/projects/test-area-oox/global/networks/default",
"networkIP": "10.162.0.7",
"subnetwork": "https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/northamerica-northeast1/subnetworks/default"
}
],
"scheduling": {
"automaticRestart": true,
"onHostMaintenance": "MIGRATE",
"preemptible": false
},
"selfLink": "https://www.googleapis.com/compute/v1/projects/test-area-oox/zones/northamerica-northeast1-a/instances/i-test-kkn",
"startRestricted": false,
"tags": {
"fingerprint": "42WmSpB8rSM="
},
"shortMachineType": "custom-2-2048",
"project": "test-area-oox",
"internalIp": "10.162.0.7",
"externalIp": "35.203.99.102",
"shortNetwork": "default",
"shortSubnetwork": "default",
"iconUrl": "/rest/services/assets/gcp/os_logo/debian.png",
"osImageName": "debian-9-stretch",
"osImageSelfLink": "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-9-stretch-v20190514",
"osImageSizeInGb": 0,
"bootDiskSizeInGb": 0,
"cpuCount": 2,
"memoryInGB": 2.000000,
"id": "5611478403377505138",
"name": "i-test-kkn",
"shortZone": "northamerica-northeast1-a",
"shortRegion": "northamerica-northeast1"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/instances
Retrieve a list of all instances in a given environment.
| Attributes | |
|---|---|
statusstring |
The status of the instance. One of the following values: PROVISIONING, STAGING, RUNNING, STOPPING, STOPPED, SUSPENDING, SUSPENDED, and TERMINATED. |
zonestring |
URL of the zone where the instance resides. |
machineTypestring |
URL of the machine type resource used by this instance. |
cpuPlatformstring |
The CPU platform used by this instance. |
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
deletionProtectionstring |
Whether the resource should be protected against deletion. |
disksArray[Disk] |
Array of disks associated with this instance. |
kindstring |
Type of the resource. |
labelFingerprintstring |
A base64-encoded string. A hash of the label's contents and used for optimistic locking. |
metadataobject |
The metadata key/value pairs assigned to this instance. |
networkInterfacesArray[object] |
An array of network configurations for this instance. |
schedulingobject |
Sets the scheduling options for this instance. |
selfLinkstring |
Server-defined URL for this resource. |
startRestrictedboolean |
Whether a VM has been restricted for start because Compute Engine has detected suspicious activity. |
tagsobject |
Tags to apply to this instance. Tags are used to identify valid sources or targets for network firewalls and are specified by the client during instance creation. |
shortMachineTypestring |
A short version of the machineType name. |
projectstring |
The project where the instance resides. |
internalIpstring |
The instance's internal IP. |
shortNetworkstring |
The network to which the instance is connected to. |
shortSubnetworkstring |
The sub-network within the network the instance is connected to. |
iconUrlstring |
Icon representing the OS installed on the instance's boot disk. |
osImageNamestring |
The name of the OS image installed on the instance's boot disk. |
osImageSelfLinkstring |
The full URL to the OS image. |
osImageSizeInGbstring |
The size of the OS image. |
bootDiskSizeInGbstring |
The size of the instance's boot disk. |
cpuCountstring |
The number of vCPUs for the machine type. |
memoryInGBstring |
The memory size for the machine name. |
idUUID |
The id of the instance. |
namestring |
The display name of the instance. |
shortZonestring |
A short version of the zone name. |
shortRegionstring |
A short version of the region name. |
Retrieve an instance
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/instances/5611478403377505138"
The above command returns a JSON structured like this:
{
"data": {
"status": "RUNNING",
"zone": "https://www.googleapis.com/compute/v1/projects/test-area-oox/zones/northamerica-northeast1-a",
"machineType": "https://www.googleapis.com/compute/v1/projects/test-area-oox/zones/northamerica-northeast1-a/machinetypes/f1-micro",
"cpuPlatform": "Intel Skylake",
"creationTimestamp": "2019-04-19T12:12:30.756-07:00",
"deletionProtection": false,
"disks": [
{
"autoDelete": true,
"boot": true,
"deviceName": "i-test-kkn",
"guestOsFeatures": [
{
"type": "VIRTIO_SCSI_MULTIQUEUE"
}
],
"index": 0,
"interface": "SCSI",
"kind": "compute#attachedDisk",
"licenses": [
"https://www.googleapis.com/compute/v1/projects/debian-cloud/global/licenses/debian-9-stretch"
],
"mode": "READ_WRITE",
"source": "https://www.googleapis.com/compute/v1/projects/test-area-oox/zones/northamerica-northeast1-a/disks/i-test-kkn",
"type": "PERSISTENT"
}
],
"kind": "compute#instance",
"labelFingerprint": "42WmSpB8rSM=",
"metadata": {
"fingerprint": "WFshDDge4fM=",
"items": [
{
"key": "startup-script",
"value": "#! /bin/bash\napt-get update\nEOF"
}
],
"kind": "compute#metadata"
},
"networkInterfaces": [
{
"accessConfigs": [
{
"kind": "compute#accessConfig",
"name": "external-nat",
"natIP": "35.203.99.102",
"networkTier": "PREMIUM",
"type": "ONE_TO_ONE_NAT"
}
],
"fingerprint": "NG6-4Cdf0KA=",
"kind": "compute#networkInterface",
"name": "nic0",
"network": "https://www.googleapis.com/compute/v1/projects/test-area-oox/global/networks/default",
"networkIP": "10.162.0.7",
"subnetwork": "https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/northamerica-northeast1/subnetworks/default"
}
],
"scheduling": {
"automaticRestart": true,
"onHostMaintenance": "MIGRATE",
"preemptible": false
},
"selfLink": "https://www.googleapis.com/compute/v1/projects/test-area-oox/zones/northamerica-northeast1-a/instances/i-test-kkn",
"startRestricted": false,
"tags": {
"fingerprint": "42WmSpB8rSM="
},
"shortMachineType": "custom-2-2048",
"project": "test-area-oox",
"internalIp": "10.162.0.7",
"externalIp": "35.203.99.102",
"shortNetwork": "default",
"shortSubnetwork": "default",
"iconUrl": "/rest/services/assets/gcp/os_logo/debian.png",
"osImageName": "debian-9-stretch",
"osImageSelfLink": "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-9-stretch-v20190514",
"osImageSizeInGb": 0,
"bootDiskSizeInGb": 0,
"cpuCount": 2,
"memoryInGB": 2.000000,
"id": "5611478403377505138",
"name": "i-test-kkn",
"shortZone": "northamerica-northeast1-a",
"shortRegion": "northamerica-northeast1"
}
}
GET /services/:service_code/:environment_name/instances/:id
Retrieve an instance in a given environment.
| Attributes | |
|---|---|
statusstring |
The status of the instance. One of the following values: PROVISIONING, STAGING, RUNNING, STOPPING, STOPPED, SUSPENDING, SUSPENDED, and TERMINATED. |
zonestring |
URL of the zone where the instance resides. |
machineTypestring |
URL of the machine type resource used by this instance. |
cpuPlatformstring |
The CPU platform used by this instance. |
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
deletionProtectionstring |
Whether the resource should be protected against deletion. |
disksArray[Disk] |
Array of disks associated with this instance. |
kindstring |
Type of the resource. |
labelFingerprintstring |
A base64-encoded string. A hash of the label's contents and used for optimistic locking. |
metadataobject |
The metadata key/value pairs assigned to this instance. |
networkInterfacesArray[object] |
An array of network configurations for this instance. |
schedulingobject |
Sets the scheduling options for this instance. |
selfLinkstring |
Server-defined URL for this resource. |
startRestrictedboolean |
Whether a VM has been restricted for start because Compute Engine has detected suspicious activity. |
tagsobject |
Tags to apply to this instance. Tags are used to identify valid sources or targets for network firewalls and are specified by the client during instance creation. |
shortMachineTypestring |
A short version of the machineType name. |
projectstring |
The project where the instance resides. |
internalIpstring |
The instance's internal IP. |
shortNetworkstring |
The network to which the instance is connected to. |
shortSubnetworkstring |
The sub-network within the network the instance is connected to. |
iconUrlstring |
Icon representing the OS installed on the instance's boot disk. |
osImageNamestring |
The name of the OS image installed on the instance's boot disk. |
osImageSelfLinkstring |
The full URL to the OS image. |
osImageSizeInGbstring |
The size of the OS image. |
bootDiskSizeInGbstring |
The size of the instance's boot disk. |
cpuCountstring |
The number of vCPUs for the machine type. |
memoryInGBstring |
The memory size for the machine name. |
idUUID |
The id of the instance. |
namestring |
The display name of the instance. |
shortZonestring |
A short version of the zone name. |
shortRegionstring |
A short version of the region name. |
Create an instance
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/instances"
Request body examples:
// Create an instance with an existing IP
{
"name": "my-instance",
"shortRegion": "northamerica-northeast1",
"shortZone": "northamerica-northeast1-a",
"bootDiskType": "pd-standard",
"bootDiskSizeInGb": "10",
"cpuCount": "2",
"memoryInGB": "4.5",
"osImageSelfLink": "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-9-stretch-v20190514",
"shortSubnetwork": "production-net",
"shortIP": "my-ip-name",
"startupScript": "#! /bin/bash\napt-get update\nEOF"
}
// Create an instance with a new static IP
{
"name": "my-instance",
"shortRegion": "northamerica-northeast1",
"shortZone": "northamerica-northeast1-a",
"bootDiskType": "pd-standard",
"bootDiskSizeInGb": "10",
"cpuCount": "2",
"memoryInGB": "4.5",
"osImageSelfLink": "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-9-stretch-v20190514",
"shortSubnetwork": "staging-net",
"reserveStaticIP": true
}
// Create an instance with an ephemeral IP
{
"name": "my-instance",
"shortRegion": "northamerica-northeast1",
"shortZone": "northamerica-northeast1-a",
"bootDiskType": "pd-standard",
"bootDiskSizeInGb": "10",
"cpuCount": "2",
"memoryInGB": "4.5",
"osImageSelfLink": "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-9-stretch-v20190514",
"shortSubnetwork": "development-net",
"ephemeralIP": true
}
// Create an instance with no external IP
{
"name": "my-instance",
"shortRegion": "northamerica-northeast1",
"shortZone": "northamerica-northeast1-a",
"bootDiskType": "pd-standard",
"bootDiskSizeInGb": "10",
"cpuCount": "2",
"memoryInGB": "4.5",
"osImageSelfLink": "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-9-stretch-v20190514",
"shortSubnetwork": "demo-net",
}
POST /services/:service_code/:environment_name/instances
Create a new instance.
| Required | |
|---|---|
namestring |
The display name of the instance. |
shortRegionstring |
A short version of the region name. |
shortZonestring |
A short version of the zone name. |
bootDiskTypestring |
The boot disk type. Choices are 'pd-standard' or 'pd-ssd'. |
bootDiskSizeInGb string |
The size of the boot disk in GB. Acceptable values are 1 to 2000, inclusive. |
cpuCountstring |
Updated number of vCPUs of instance. |
memoryInGBstring |
Updated memory of instance. |
osImageSelfLinkstring |
The full URL to the OS image. |
shortSubnetworkstring |
The subnet that the instance is attached to upon creation. (Note that the subnet must be in the same region as the instance). |
| Optional | |
|---|---|
reserveStaticIPboolean |
If the value is true, a new static IP would be reserved and provided to the resource. |
shortIPstring |
The name of an existing regional external IP address assigned to this instance in the same region. This argument is only valid in conjunction with reserveStaticIP and ephemeral IP being false. |
ephemeralIPboolean |
If the value is false, reserve static IP is false and if no shortIP is provided the instance won't have an external IP. If the value is true, an ephemeral external IP address will be assigned. |
startupScriptstring |
A startup script metadata item to run every time the instance boots up. |
Delete an instance
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/instances/5611478403377505138"
Request body example:
{
"deleteSnapshots": true,
}
DELETE /services/:service_code/:environment_name/instances/:id
Delete an existing instance.
| Optional | |
|---|---|
deleteSnapshotsboolean |
Whether captured snapshops of associated auto-deletable disks should be deleted |
Change machine type
A machine type determines the number of vCPUs and the size of the memory allocated to new instances.
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/instances/6564997542943928188?operation=resize"
Request body example:
{
"cpuCount": "2",
"memoryInGB": "4.5"
}
POST /services/:service_code/:environment_name/instances/:id?operation=resize
Update the number of vCPUs and memory of an existing instance.
| Optional | |
|---|---|
cpuCountstring |
Updated number of vCPUs of instance. |
memoryInGBstring |
Updated memory of instance. |
Change external IP
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/instances/6564997542943928188?operation=change_external_ip"
Request body examples:
// Changing the IP to an ephemeral IP, just leave it empty
{ }
// Changing the IP to a new static IP
{
"reserveStaticIP" : true
}
// Changing the IP to an existing IP
{
"shortIP" : "your-ip-name"
}
POST /services/:service_code/:environment_name/instances/:id?operation=change_external_ip
Change the static external IP of an existing instance.
| Optional | |
|---|---|
shortIPString |
The name of a static external IP in the same region as the instance. |
reserveStaticIPboolean |
Specify to reserve a new external IP for the instance. Cannot be specified when 'shortIP' is also specified. |
Get SSH command
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/instances/6564997542943928188?operation=get_ssh"
Request body example:
{
"sshKeyId": "my-ssh-key"
}
The above command(s) return(s) JSON structured like this:
{
"taskId": "c50390c7-9d5b-4af4-a2da-e2a2678a83e8",
"taskStatus": "PENDING"
}
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/tasks/c50390c7-9d5b-4af4-a2da-e2a2678a83e8"
The above command(s) return(s) JSON structured like this:
{
"data": {
"id": "c50390c7-9d5b-4af4-a2da-e2a2678a83e8",
"status": "SUCCESS",
"created": "2021-04-20T20:58:59.952881-04:00",
"result": {
"id": "6564997542943928188",
"command": "ssh my-user@192.0.0.1"
}
}
}
POST /services/:service_code/:environment_name/instances/:id?operation=get_ssh
Retrieve a command to allow you to SSH into a give running instance.
| Required | |
|---|---|
sshKeyIdstring |
The id of an existing SSH key already save in the environment. Mutually exclusive with publicKey. |
publicKeystring |
The SSH key text. Mutually exclusive with sshKeyId. A new SSH key will be save in the environment. |
| Attributes | |
|---|---|
idstring |
The task ID. |
statusstring |
The status. |
createdDate |
The task's creation date. |
resultObject |
The task result, containing details required to access the instance's console. |
result.idString |
The id of the instance being accessed by the SSH command. |
result.commandString |
The command to execute to access the instance's console. |
Set Windows password
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/instances/6564997542943928188?operation=set_windows_password"
Request body example:
{
"username": "my-user"
}
The above command(s) return(s) JSON structured like this:
{
"taskId": "c50390c7-9d5b-4af4-a2da-e2a2678a83e8",
"taskStatus": "PENDING"
}
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/tasks/c50390c7-9d5b-4af4-a2da-e2a2678a83e8"
The above command(s) return(s) JSON structured like this:
{
"data": {
"id": "c50390c7-9d5b-4af4-a2da-e2a2678a83e8",
"status": "SUCCESS",
"created": "2021-04-20T20:58:59.952881-04:00",
"result": {
"externalIpAddress": "192.0.0.1",
"username": "my-user",
"password": "my-generated-password"
}
}
}
POST /services/:service_code/:environment_name/instances/:id?operation=set_windows_password
Set and retrieve a generated password to a given user on a running Windows instance.
| Required | |
|---|---|
usernamestring |
The username. |
| Attributes | |
|---|---|
idstring |
The task ID. |
statusstring |
The status. |
createdDate |
The task's creation date. |
resultObject |
The task result, containing details required to access the instance's console. |
result.externalIpAddressString |
The instance's external IP address. |
result.usernameString |
The username. |
result.passwordString |
The password for the given user. |
Manage group membership
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/instances/2986056884972096897?operation=manage_group_membership"
Request body example:
{
"shortGroups": ["my-group"]
}
POST /services/:service_code/:environment_name/instancegroups/:id?operation=manage_group_membership
Manage an instance's membership to groups.
| Required | |
|---|---|
shortGroupsarray[string] |
Array of group names representing the current groups the instance belongs to. If a group, which the instance currently belongs to, is not kept in the list, the instance will be removed from the group. If the array is empty, the instance will be removed from all the groups it currently belongs to. |
Start an instance
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/instances/6564997542943928188?operation=start"
POST /services/:service_code/:environment_name/instances/:id?operation=start
Start an existing instance. The instance must be in the TERMINATED status for this operation to work.
Stop an instance
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/instances/6564997542943928188?operation=stop"
POST /services/:service_code/:environment_name/instances/:id?operation=stop
Stop an existing instance. The instance must be in either the RUNNING or STOPPING status for this operation to work. The default behavior is that the instance (denote by id) will be stopped gracefully.
Edit a startup script
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/instances/6564997542943928188?operation=edit_startup_script"
Request body example:
{
"startupScript": "#! /bin/bash\ncat <<EOF > /var/www/html/index.html\n<html><body><h1>Hello World</h1>\n<p>This page was created from a simple startup script!</p>\n</body></html>\nEOF"
}
POST /services/:service_code/:environment_name/instances/:id?operation=edit_startup_script
Edit the startup script for an existing instance.
| Required | |
|---|---|
startupScriptstring |
A startup script metadata item to run every time the instance boots up. |
Instance groups
An instance group is a collection of VM instances that you can manage as a single entity. Instance groups are used to apply load balancing to groups of heterogeneous instances. In a load balancer setup, an instance group can be used as part of a backend service.
List instance groups
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/instancegroups"
The above command returns a JSON structured like this:
{
"data": [
{
"creationTimestamp": "2019-09-06T12:28:47.389-07:00",
"description": "",
"fingerprint": "42WmSpB8rSM=",
"kind": "compute#instanceGroup",
"namedPorts": [
{
"name": "http",
"port": 80
}
],
"network": "https://www.googleapis.com/compute/v1/projects/test-area/global/networks/default",
"selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/zones/us-central1-a/instanceGroups/ig-test-vmd",
"size": 0,
"subnetwork": "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/subnetworks/default",
"zone": "https://www.googleapis.com/compute/v1/projects/test-area/zones/us-central1-a",
"id": "2986056884972096897",
"name": "ig-test-vmd",
"shortZone": "us-central1-a",
"shortRegion": "us-central1"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/instancegroups
Retrieve a list of all instance groups in a given environment.
| Attributes | |
|---|---|
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
descriptionstring |
An optional description of this resource. |
fingerprintstring |
A short sequence of bytes used to identify the named ports. |
idUUID |
The id of the instance group. |
kindstring |
Type of the resource. |
namestring |
The display name of the instance group. |
namedPortsobject |
Assigns a name to a port number. This allows the system to reference ports by the assigned name instead of a port number. Named ports apply to all instances in this instance group. |
networkstring |
The network to which the instance group is connected to. |
selfLinkstring |
Server-defined URL for this resource. |
shortRegionstring |
A short version of the region name. |
shortZonestring |
A short version of the zone name. |
sizeinteger |
The number of instances in the group. |
subnetworkstring |
The sub-network within the network the instance group is connected to. |
zonestring |
URL of the zone where the instance group resides. |
Retrieve an instance group
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/instancegroups/2986056884972096897"
The above command returns a JSON structured like this:
{
"data": {
"creationTimestamp": "2019-09-06T12:28:47.389-07:00",
"description": "",
"fingerprint": "42WmSpB8rSM=",
"kind": "compute#instanceGroup",
"namedPorts": [
{
"name": "http",
"port": 80
}
],
"network": "https://www.googleapis.com/compute/v1/projects/test-area/global/networks/default",
"selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/zones/us-central1-a/instanceGroups/ig-test-vmd",
"size": 0,
"subnetwork": "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/subnetworks/default",
"zone": "https://www.googleapis.com/compute/v1/projects/test-area/zones/us-central1-a",
"id": "2986056884972096897",
"name": "ig-test-vmd",
"shortZone": "us-central1-a",
"shortRegion": "us-central1"
}
}
GET /services/:service_code/:environment_name/instancegroups/:id
Retrieve an instance group in a given environment.
| Attributes | |
|---|---|
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
descriptionstring |
An optional description of this resource. |
fingerprintstring |
A short sequence of bytes used to identify the named ports. |
idUUID |
The id of the instance group. |
kindstring |
Type of the resource. |
namestring |
The display name of the instance group. |
namedPortsobject |
Assigns a name to a port number. This allows the system to reference ports by the assigned name instead of a port number. Named ports apply to all instances in this instance group. |
networkstring |
The network to which the instance group is connected to. |
selfLinkstring |
Server-defined URL for this resource. |
shortRegionstring |
A short version of the region name. |
shortZonestring |
A short version of the zone name. |
sizeinteger |
The number of instances in the group. |
subnetworkstring |
The sub-network within the network the instance group is connected to. |
zonestring |
URL of the zone where the instance group resides. |
Create an instance group
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/instancegroups"
Request body example:
{
"name": "my-group",
"shortRegion": "northamerica-northeast1",
"shortZone": "northamerica-northeast1-b",
"shortNetwork": "default",
"shortSubnetwork": "default",
"shortInstances": ["instance-1"]
}
POST /services/:service_code/:environment_name/instancegroups
Create a new instance group.
| Required | |
|---|---|
namestring |
The display name of the instance group. |
shortZonestring |
A short version of the zone name. |
| Optional | |
|---|---|
shortInstancesarray[string] |
Array of instance names to add to the instance group upon creation. All these instances should belong to the zone provided and should be in the same subnet. |
shortNetworkstring |
The network to which the instance group is connected to. |
shortRegionstring |
A short version of the region name. |
shortSubnetworkstring |
The sub-network within the network the instance group is connected to. This will only be applied to the instance group if instances are being bound at creation time, if not, only the network will be applied to the instance group. |
Delete an instance group
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/instancegroups/2986056884972096897"
DELETE /services/:service_code/:environment_name/instancegroups/:id
Delete an existing instance group.
Manage instance members
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/instancegroups/2986056884972096897?operation=manage_instance_members"
Request body example:
{
"shortInstances": ["instance-2"]
}
POST /services/:service_code/:environment_name/instancegroups/:id?operation=manage_instance_members
Manage instance members in an existing instance group.
| Required | |
|---|---|
shortInstancesarray[string] |
Array of instance names representing the current members of the instance group. If a current instance member is not kept in the list, it will be removed from the group. If the array is empty, all the instance members will be removed. |
Disks
Deploy and manage your disks.
List disks
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/disks"
The above command returns a JSON structured like this:
{
"data": [
{
"creationTimestamp": "2019-05-07T08:46:06.488-07:00",
"sizeGb": "10",
"zone": "https://www.googleapis.com/compute/v1/projects/test-area/zones/northamerica-northeast1-a",
"status": "ATTACHED",
"selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/zones/northamerica-northeast1-a/disks/d-test-dow",
"type": "https://www.googleapis.com/compute/v1/projects/test-area/zones/northamerica-northeast1-a/diskTypes/pd-standard",
"lastAttachTimestamp": "2019-05-07T08:46:11.989-07:00",
"users": [
"https://www.googleapis.com/compute/v1/projects/test-area/zones/northamerica-northeast1-a/instances/i-test-aum"
],
"labelFingerprint": "42WmSpB8rSM=",
"physicalBlockSizeBytes": "4096",
"kind": "compute#disk",
"shortUsers": "i-test-aum",
"shortType": "pd-standard",
"attachMode": "READ_WRITE",
"autoDelete": false,
"id": "5333546534174463697",
"name": "d-test-dow",
"shortZone": "northamerica-northeast1-a",
"shortRegion": "northamerica-northeast1"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/disks
Retrieve a list of all disks in a given environment.
| Attributes | |
|---|---|
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
sizeGb string |
The size of the disk in GB. Acceptable values are 1 to 65536, inclusive. |
zonestring |
URL of the zone where the instance resides. |
statusstring |
The status of the disk. One of the following values: READY, CREATING, ATTACHING, ATTACHED, DETACHING, RESIZING, DELETING, and DEPRECATED. |
selfLinkstring |
Server-defined URL for this resource. |
typestring |
URL of the disk type resource describing which disk type to use to create the disk. Choices are ':url/pd-standard' or ':url/pd-ssd'. |
lastAttachTimestampstring |
Timestamp representing the last time the disk was attached. |
usersArray[string] |
Links to the instances the disk is attached to. |
labelFingerprintstring |
A base64-encoded string. A hash of the label's contents and used for optimistic locking. |
physicalBlockSizeBytesstring |
Physical block size of the persistent disk, in bytes. Currently supported sizes are 4096 and 16384. |
kindstring |
Type of the resource. |
shortUsersstring |
The names of the instances the disk is attached to. |
shortTypestring |
The disk type. Choices are 'pd-standard' or 'pd-ssd'. |
attach_modestring |
The mode used to attach the disk to instances. Valid modes are READ_WRITE or READ_ONLY. |
autoDeleteboolean |
Whether the resource should be deleted when the instance it's attached to are deleted. |
idUUID |
The id of the instance. |
namestring |
The display name of the instance. |
shortZonestring |
A short version of the zone name. |
shortRegionstring |
A short version of the region name. |
Retrieve a disk
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/disks/5333546534174463697"
The above command returns a JSON structured like this:
{
"data": {
"creationTimestamp": "2019-05-07T08:46:06.488-07:00",
"sizeGb": "10",
"zone": "https://www.googleapis.com/compute/v1/projects/test-area/zones/northamerica-northeast1-a",
"status": "ATTACHED",
"selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/zones/northamerica-northeast1-a/disks/d-test-dow",
"type": "https://www.googleapis.com/compute/v1/projects/test-area/zones/northamerica-northeast1-a/diskTypes/pd-standard",
"lastAttachTimestamp": "2019-05-07T08:46:11.989-07:00",
"users": [
"https://www.googleapis.com/compute/v1/projects/test-area/zones/northamerica-northeast1-a/instances/i-test-aum"
],
"labelFingerprint": "42WmSpB8rSM=",
"physicalBlockSizeBytes": "4096",
"kind": "compute#disk",
"shortUsers": "i-test-aum",
"shortType": "pd-standard",
"attachMode": "READ_WRITE",
"autoDelete": false,
"id": "5333546534174463697",
"name": "d-test-dow",
"shortZone": "northamerica-northeast1-a",
"shortRegion": "northamerica-northeast1"
}
}
GET /services/:service_code/:environment_name/disks/:id
Retrieve a disk in a given environment.
| Attributes | |
|---|---|
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
sizeGb string |
The size of the disk in GB. Acceptable values are 1 to 65536, inclusive. |
zonestring |
URL of the zone where the instance resides. |
statusstring |
The status of the disk. One of the following values: READY, CREATING, ATTACHING, ATTACHED, DETACHING, RESIZING, DELETING, and DEPRECATED. |
selfLinkstring |
Server-defined URL for this resource. |
typestring |
URL of the disk type resource describing which disk type to use to create the disk. Choices are ':url/pd-standard' or ':url/pd-ssd'. |
lastAttachTimestampstring |
Timestamp representing the last time the disk was attached. |
usersArray[string] |
Links to the instances the disk is attached to. |
labelFingerprintstring |
A base64-encoded string. A hash of the label's contents and used for optimistic locking. |
physicalBlockSizeBytesstring |
Physical block size of the persistent disk, in bytes. Currently supported sizes are 4096 and 16384. |
kindstring |
Type of the resource. |
shortUsersstring |
The names of the instances the disk is attached to. |
shortTypestring |
The disk type. Choices are 'pd-standard' or 'pd-ssd'. |
attachModestring |
The mode used to attach the disk to instances. Valid modes are READ_WRITE or READ_ONLY. |
autoDeleteboolean |
Whether the resource should be deleted when the instance it's attached to are deleted. |
idUUID |
The id of the instance. |
namestring |
The display name of the instance. |
shortZonestring |
A short version of the zone name. |
shortRegionstring |
A short version of the region name. |
Create a disk
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/disks"
Request body example:
{
"name": "my-disk",
"shortRegion": "northamerica-northeast1",
"shortZone": "northamerica-northeast1-a",
"shortType": "pd-standard",
"sizeGb": "10"
}
POST /services/:service_code/:environment_name/disks
Create a new disk
| Required | |
|---|---|
namestring |
The display name of the instance. |
shortRegionstring |
A short version of the region name. |
shortZonestring |
A short version of the zone name. |
shortTypestring |
The disk type. Choices are 'pd-standard' or 'pd-ssd'. |
sizeGb string |
The size of the disk in GB. Acceptable values are 1 to 65536, inclusive. |
| Optional | |
|---|---|
physicalBlockSizeBytesstring |
Physical block size of the persistent disk, in bytes. Currently supported sizes are 4096 and 16384. Defaults to 4096. |
Delete a disk
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/disks/5333546534174463697"
Request body example:
{
"deleteSnapshots": true,
}
DELETE /services/:service_code/:environment_name/disks/:id
Destroy an existing disk. A disk can only be deleted if it's not attached to an instance.
| Optional | |
|---|---|
deleteSnapshotsboolean |
Whether captured snapshops should be deleted |
Attach a disk to an instance
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/disks/5333546534174463697?operation=attach"
Request body example:
{
"shortUsers": "5611478403377505138",
"attachMode": "READ_WRITE",
"autoDelete": false
}
POST /services/:service_code/:environment_name/disks/:id?operation=attach
Attach an existing disk to an instance.
| Required | |
|---|---|
shortUsersstring |
The id of the instance to which the created disk should be attached |
attachModestring |
The mode used to attach the disk to the instance. Valid modes are READ_WRITE or READ_ONLY. |
autoDeleteboolean |
Whether the resource should be deleted when the instance it's attached to are deleted. If attachMode is READ_ONLY, autoDelete has to be false. |
Detach a disk from an instance
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/disks/5333546534174463697?operation=detach"
Request body example:
{
"shortUsers": "5611478403377505138"
}
POST /services/:service_code/:environment_name/disks/:id?operation=detach
Detach an existing disk from a given instance.
| Required | |
|---|---|
shortUsersstring |
The id of the instance to which the created disk should be attached. |
Resize a disk
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/disks/5333546534174463697?operation=resize"
Request body example:
{
"sizeGb": "50"
}
POST /services/:service_code/:environment_name/disks/:id?operation=resize
Resize an existing disk.
| Required | |
|---|---|
sizeGb string |
The size of the disk in GB. Valid values are 1 to 65536, inclusive, unless this is an instance's boot disk, then the valid values are 1 to 2000. |
Take a snapshot of a disk
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/disks/5333546534174463697?operation=snapshot"
Request body example:
{
"snapshotName": "my-snapshot"
}
POST /services/:service_code/:environment_name/disks/:id?operation=snapshot
Take a snapshot of a persistent disk.
| Optional | |
|---|---|
snapshotName string |
The name of the snapshot. A default value set if a snapshot name is not provided. |
SSH keys
SSH keys are managed at the environment level.
List SSH keys
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/sshkeys"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "user1",
"name": "user1",
"publicKey": "ssh-rsa mypublickey user1@host.com"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/sshkeys
Retrieve a list of all SSH keys in an environment.
| Attributes | |
|---|---|
idstring |
The SSH key's id. |
namestring |
The name of the SSH key. |
publicKeystring |
A string representing the protocol, public key and username. GCP SSH keys documentation |
Retrieve an SSH key
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/sshkeys/user1"
The above command returns a JSON structured like this:
{
"data": {
"id": "user1",
"name": "user1",
"publicKey": "ssh-rsa mypublickey user1@host.com"
}
}
GET /services/:service_code/:environment_name/sshkeys/:id
Retrieve information about an SSH key of an environment.
| Attributes | |
|---|---|
idstring |
The SSH key's id. |
namestring |
The name of the SSH key. |
publicKeystring |
A string representing the protocol, public key and username. GCP SSH keys documentation |
Add an SSH key
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/sshkeys"
Request body example:
{
"name": "user1",
"publicKey": "ssh-rsa mypublickey user1@host.com"
}
POST /services/:service_code/:environment_name/sshkeys
Add an SSH key to the environment.
| Attributes | |
|---|---|
namestring |
The name of the SSH key. |
publicKeystring |
A string representing the protocol, public key and username. GCP SSH keys documentation |
Delete an SSH key
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/sshkeys/user1"
DELETE /services/:service_code/:environment_name/sshkeys/:name
Delete an existing SSH key from the environment.
Health checks
Health checking mechanisms determine whether VM instances respond properly to traffic.
List health checks
curl -X GET \
-H 'MC-Api-key: your_api_key'
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/healthchecks"
The above command returns a JSON structured like this:
{
"data": [
{
"checkIntervalSec": 10,
"creationTimestamp": "2019-09-18T12:39:48.982-07:00",
"description": "",
"healthyThreshold": 2,
"id": "5930212998788364011",
"kind": "compute#healthCheck",
"name": "hc-name-xxx",
"selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/global/healthChecks/healthcheckname",
"httpHealthCheck": {
"host": "",
"port": 80,
"portName": "http",
"proxyHeader": "NONE",
"requestPath": "/"
},
"timeoutSec": 5,
"type": "HTTP",
"unhealthyThreshold": 3,
"portNumber": "80"
}
],
"metadata": {
"recordCount": 1
}
}
GET /service/:service_code/:environment_name/healthchecks
Retrieve a list of all health checks.
| Attributes | |
|---|---|
checkIntervalSecint |
How often (in seconds) to send a health check. The default value is 5 seconds. |
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
description string |
An optional description of this resource. Provide this property when you create the resource. |
healthyThreshold |
A so-far unhealthy instance will be marked healthy after this many consecutive successes. The default value is 2. |
httpHealthCheck object |
When the type is set to HTTP, this object represents the health check. |
httpSHealthCheck object |
When the type is set to HTTPS, this object represents the health check. |
idstring |
The unique identifier for the resource. This identifier is defined by the server. |
kindstring |
Type of the resource. |
namestring |
Name of the resource. Provided by the client when the resource is created. |
selfLinkstring |
Server-defined URL for this resource. |
timeoutSecint |
How long (in seconds) to wait before claiming failure. The default value is 5 seconds. It is invalid for timeoutSec to have greater value than checkIntervalSec. |
typestring |
Specifies the type of the health check, either HTTP or HTTPS. If not specified, the default is HTTP. Exactly one of the protocol-specific health check field must be specified, which must match type field. |
unhealthyThresholdint |
A so-far healthy instance will be marked unhealthy after this many consecutive failures. The default value is 2. |
portNumberstring |
The port number for health check. |
Retrieve a health check
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/healthchecks/5930212998788364011"
The above command returns a JSON structured like this:
{
"data": {
"checkIntervalSec": 10,
"creationTimestamp": "2019-09-18T12:39:48.982-07:00",
"description": "",
"healthyThreshold": 2,
"id": "5930212998788364011",
"kind": "compute#healthCheck",
"name": "hc-name-xxx",
"selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/global/healthChecks/firsthealthcheck",
"httpHealthCheck": {
"host": "",
"port": 80,
"portName": "http",
"proxyHeader": "NONE",
"requestPath": "/"
},
"timeoutSec": 5,
"type": "HTTP",
"unhealthyThreshold": 3,
"portNumber": "80"
}
}
GET /services/:service_code/:environment_name/healthchecks/:id
Retrieve a health check in a given environment.
| Attributes | |
|---|---|
checkIntervalSecint |
How often (in seconds) to send a health check. The default value is 5 seconds. |
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
description string |
An optional description of this resource. Provide this property when you create the resource. |
healthyThresholdint |
A so-far unhealthy instance will be marked healthy after this many consecutive successes. The default value is 2. |
httpHealthCheck object |
When the type is set to HTTP, this object represents the health check. |
httpSHealthCheck object |
When the type is set to HTTPS, this object represents the health check. |
idstring |
The unique identifier for the resource. This identifier is defined by the server. |
kindstring |
Type of the resource. |
namestring |
Name of the resource. Provided by the client when the resource is created. |
selfLinkstring |
Server-defined URL for this resource. |
timeoutSecint |
How long (in seconds) to wait before claiming failure. The default value is 5 seconds. It is invalid for timeoutSec to have greater value than checkIntervalSec. |
typestring |
Specifies the type of the health check, either HTTP or HTTPS. If not specified, the default is HTTP. Exactly one of the protocol-specific health check field must be specified, which must match type field. |
unhealthyThresholdint |
A so-far healthy instance will be marked unhealthy after this many consecutive failures. The default value is 2. |
portNumberstring |
The port number for health check. |
Create a health check
curl -X POST \
-H 'MC-Api-Key: your_api_key' \
-H "Content-Type: application/json" \
-d "request _body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/healthchecks"
POST /services/:service_code/:environment_name/healthchecks
Create a new health check
| Required | |
|---|---|
namestring |
The display name of the health check. |
| Optional | |
|---|---|
typestring |
Specifies the type of the health check, either HTTP or HTTPS. If not specified, the default is HTTP. |
portNumberstring |
The port number for the health check. The default is 80 for HTTP, 443 for HTTPS. |
descriptionstring |
Description of the health check. |
Delete a health check
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/healthchecks/6938691570659391640"
DELETE /services/:service_code/:environment_name/healthchecks/:id
Destroy an existing health check. A health check can only be deleted if it's not used by a backend service.
Edit a health check
curl -X PUT \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/healthchecks/6938691570659391640"
Request body example:
{
"portNumber": 80,
"type": "HTTP",
"description": "it is for test"
}
PUT /services/:service_code/:environment_name/healthchecks/:id
Edit an existing health check.
| Required | |
|---|---|
portNumberinteger |
The port number of the health check. |
| Optional | |
|---|---|
typestring |
Specifies the type of the health check, either HTTP or HTTPS. The type should be valided (If not specified, the default is HTTP). |
descriptionstring |
Description of the health check. |
Snapshots
Snapshots can be created to periodically back up data from your instances.
List snapshots
curl -X GET \
-H 'MC-Api-key: your_api_key'
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/snapshots"
The above command returns a JSON structured like this:
{
"data": [
{
"description": "This is a snapshot description",
"creationTimestamp": "2020-06-17T08:02:34.132-07:00",
"status": "READY",
"sourceDisk": "https://www.googleapis.com/compute/v1/projects/testarea/zones/northamerica-northeast1-a/disks/source-instance-name",
"sourceDiskId": "7481902077681239049",
"diskSizeGb": "10",
"storageBytes": "932828192",
"storageBytesStatus": "UP_TO_DATE",
"licenses": [
"https://www.googleapis.com/compute/v1/projects/debian-cloud/global/licenses/debian-9-stretch"
],
"selfLink": "https://www.googleapis.com/compute/v1/projects/testarea/global/snapshots/snapshot-1",
"labels": {
"sampleLabel": "label value"
},
"labelFingerprint": "6gSwJq6EkEI=",
"licenseCodes": [
"1023205"
],
"storageLocations": [
"us"
],
"kind": "compute#snapshot",
"downloadBytes": "932822788",
"id": "7059283128121212212",
"name": "snapshot-1"
},
],
"metadata": {
"recordCount": 1
}
}
GET /service/:service_code/:environment_name/snapshots
Retrieve a list of all snapshots.
| Attributes | |
|---|---|
description string |
The snapshot description. |
creationTimestamp string |
Creation timestamp in RFC3339 text format. |
status string |
The status of the snapshot. One of the following values: CREATING, DELETING, FAILED, READY, or UPLOADING. |
sourceDisk string |
The source disk used to create this snapshot. |
sourceDiskId string |
The ID value of the disk used to create this snapshot. |
diskSizeGb string |
Size of the source disk, specified in GB. |
storageBytes string |
A size of the storage used by the snapshot. |
storageBytesStatus string |
An indicator whether storageBytes is in a stable state or it is being adjusted as a result of shared storage reallocation. This status can either be UPDATING, meaning the size of the snapshot is being updated, or UP_TO_DATE, meaning the size of the snapshot is up-to-date. |
licenses Array[string] |
A list of public visible licenses that apply to this snapshot. |
selfLink string |
Server-defined URL for the resource. |
labels Object |
Mapped object containing labels applied to this snapshot. Label values may be empty. |
labelFingerprint string |
A fingerprint for the labels being applied to this snapshot. Initially generated by Compute Engine and changes after every request to modify or update labels. |
licenseCodes Array[string] |
Integer license codes indicating which licenses are attached to this snapshot. |
storageLocations Array[string] |
Cloud Storage bucket storage location of the snapshot (regional or multi-regional). |
kind string |
Type of the resource. Always compute#snapshot for Snapshot resources. |
downloadBytes string |
Number of bytes downloaded to restore a snapshot to a disk. |
id string |
The unique identifier for the resource. This identifier is defined by the server. |
name string |
Name of the resource; provided by the client when the resource is created. |
Retrieve a snapshot
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/snapshots/7059283128121212212"
The above command returns a JSON structured like this:
{
"data": {
"description": "This is a snapshot description",
"creationTimestamp": "2020-06-17T08:02:34.132-07:00",
"status": "READY",
"sourceDisk": "https://www.googleapis.com/compute/v1/projects/testarea/zones/northamerica-northeast1-a/disks/source-instance-name",
"sourceDiskId": "7481902077681239049",
"diskSizeGb": "10",
"storageBytes": "932828192",
"storageBytesStatus": "UP_TO_DATE",
"licenses": [
"https://www.googleapis.com/compute/v1/projects/debian-cloud/global/licenses/debian-9-stretch"
],
"selfLink": "https://www.googleapis.com/compute/v1/projects/testarea/global/snapshots/snapshot-1",
"labels": {
"sampleLabel": "label value"
},
"labelFingerprint": "6gSwJq6EkEI=",
"licenseCodes": [
"1023205"
],
"storageLocations": [
"us"
],
"kind": "compute#snapshot",
"downloadBytes": "932822788",
"id": "7059283128121212212",
"name": "snapshot-1"
}
}
GET /services/:service_code/:environment_name/snapshots/:id
Retrieve a specific snapshot by id.
| Attributes | |
|---|---|
description string |
The snapshot description. |
creationTimestamp string |
Creation timestamp in RFC3339 text format. |
status string |
The status of the snapshot. One of the following values: CREATING, DELETING, FAILED, READY, or UPLOADING. |
sourceDisk string |
The source disk used to create this snapshot. |
sourceDiskId string |
The ID value of the disk used to create this snapshot. |
diskSizeGb string |
Size of the source disk, specified in GB. |
storageBytes string |
A size of the storage used by the snapshot. |
storageBytesStatus string |
An indicator whether storageBytes is in a stable state or it is being adjusted as a result of shared storage reallocation. This status can either be UPDATING, meaning the size of the snapshot is being updated, or UP_TO_DATE, meaning the size of the snapshot is up-to-date. |
licenses Array[string] |
A list of public visible licenses that apply to this snapshot. |
selfLink string |
Server-defined URL for the resource. |
labels Object |
Mapped object containing labels applied to this snapshot. Label values may be empty. |
labelFingerprint string |
A fingerprint for the labels being applied to this snapshot. Initially generated by Compute Engine and changes after every request to modify or update labels. |
licenseCodes Array[string] |
Integer license codes indicating which licenses are attached to this snapshot. |
storageLocations Array[string] |
Cloud Storage bucket storage location of the snapshot (regional or multi-regional). |
kind string |
Type of the resource. Always compute#snapshot for Snapshot resources. |
downloadBytes string |
Number of bytes downloaded to restore a snapshot to a disk. |
id string |
The unique identifier for the resource. This identifier is defined by the server. |
name string |
Name of the resource; provided by the client when the resource is created. |
Create a snapshot
See take a snapshot of a disk to create a snapshot.
Delete a snapshot
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/snapshots/463325715266630842"
DELETE /services/:service_code/:environment_name/snapshots/:id
Destroy an existing snapshot. A snapshot can only be deleted if it is in READY state.
Networking
Networks
A network is an isolated network where you can place groups of resources, such as instances.
List networks
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/networks"
The above command returns a JSON structured like this:
{
"data": [
{
"autoCreateSubnetworks": true,
"creationTimestamp": "2019-03-12T07:09:22.374-07:00",
"description": "Default network for the project",
"id": "6402509859159933821",
"name": "default",
"kind": "compute#network",
"routingConfig": {
"routingMode": "REGIONAL"
},
"selfLink": "https://www.googleapis.com/compute/v1/projects/test-area-oox/global/networks/default",
"subnetworks": [
"https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/us-east1/subnetworks/default",
"https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/us-central1/subnetworks/default",
"https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/us-west2/subnetworks/default",
"https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/us-west1/subnetworks/default",
"https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/northamerica-northeast1/subnetworks/default",
"https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/us-east4/subnetworks/default"
],
"numberSubnets": 2,
"mode": "custom"
},
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/networks
Retrieve a list of all networks in an environment.
| Attributes | |
|---|---|
autoCreateSubnetworksboolean |
When set to true, the VPC network is created in "auto" mode. When set to false, the VPC network is created in "custom" mode. |
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
descriptionstring |
An optional description of this resource. |
idstring |
The network's id. |
namestring |
The network's name. |
kindstring |
Type of the resource. |
routingConfigobject |
The network-level routing configuration for this network. Used by Cloud Router to determine what type of network-wide routing behavior to enforce. RoutingMode is either REGIONAL or GLOBAL. |
selfLinkstring |
Server-defined URL for this resource. |
subnetworksArray[URL] |
Server-defined fully-qualified URLs for all subnetworks in this VPC network. |
numberSubnetsinteger |
Number of subnets in the network. |
modestring |
If autoCreateSubnetworks is true, then auto, else custom. |
Retrieve a network
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/networks/6402509859159933821"
The above command returns a JSON structured like this:
{
"data": {
"autoCreateSubnetworks": true,
"creationTimestamp": "2019-03-12T07:09:22.374-07:00",
"description": "Default network for the project",
"id": "6402509859159933821",
"name": "default",
"kind": "compute#network",
"routingConfig": {
"routingMode": "REGIONAL"
},
"selfLink": "https://www.googleapis.com/compute/v1/projects/test-area-oox/global/networks/default",
"subnetworks": [
"https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/us-east1/subnetworks/default",
"https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/us-central1/subnetworks/default",
"https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/us-west2/subnetworks/default",
"https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/us-west1/subnetworks/default",
"https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/northamerica-northeast1/subnetworks/default",
"https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/us-east4/subnetworks/default"
],
"numberSubnets": 2,
"mode": "custom"
}
}
GET /services/:service_code/:environment_name/networks/:id
Retrieve information about a network.
| Attributes | |
|---|---|
autoCreateSubnetworksboolean |
When set to true, the VPC network is created in "auto" mode. When set to false, the VPC network is created in "custom" mode. |
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
descriptionstring |
An optional description of this resource. |
idstring |
The network's id. |
namestring |
The network's name. |
kindstring |
Type of the resource. |
routingConfigobject |
The network-level routing configuration for this network. Used by Cloud Router to determine what type of network-wide routing behavior to enforce. RoutingMode is either REGIONAL or GLOBAL. |
selfLinkstring |
Server-defined URL for this resource. |
subnetworksArray[URL] |
Server-defined fully-qualified URLs for all subnetworks in this VPC network. |
numberSubnetsinteger |
Number of subnets in the network. |
modestring |
If autoCreateSubnetworks is true, then auto, else custom. |
Create a network
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/networks"
Request body example for network in auto subnet creation mode:
{
"name": "vpc-name",
"autoCreateSubnetworks": true
}
Request body example for network in custom subnet creation mode:
{
"name": "vpc-name",
"subnetName": "subnet-name",
"subnetShortRegion": "northamerica-northeast1",
"subnetIpCidrRange": "10.0.0.0/20"
}
POST /services/:service_code/:environment_name/networks
Create a new network and attach subnet
| Required in auto mode | |
|---|---|
namestring |
The display name of the network. |
autoCreateSubnetworksboolean |
Whether subnets will be automatically created for each region. |
| Required in custom mode | |
|---|---|
namestring |
The display name of the network. |
subnetNamestring |
The display name of the subnet. |
subnetShortRegionstring |
A short version of the region name of the subnet. |
subnetIpCidrRangestring |
The CIDR IP range of the subnet. |
| Optional | |
|---|---|
descriptionstring |
Description of the network. |
Delete a network
curl -X DELETE \
-H "mc-api-key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/networks/6402509859159933821"
DELETE /services/:service_code/:environment_name/networks/:id
Delete an existing network.
Firewall rules
Firewall allows you to control inbound and outbound traffic to your environment.
List firewall rules
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/firewallrules"
The above command returns a JSON structured like this:
{
"data": [
{
"allowed": [
{
"IPProtocol": "tcp",
"ports": [
"80"
]
}
],
"creationTimestamp": "2019-03-13T13:28:49.840-07:00",
"description": "",
"direction": "INGRESS",
"disabled": false,
"id": "4890726785951782638",
"kind": "compute#firewall",
"logConfig": {
"enable": false
},
"name": "default-allow-http",
"network": "https://www.googleapis.com/compute/v1/projects/flo-cmc-gcp-cay/global/networks/default",
"priority": 1000,
"selfLink": "https://www.googleapis.com/compute/v1/projects/flo-cmc-gcp-cay/global/firewalls/default-allow-http",
"sourceRanges": [
"0.0.0.0/0"
],
"targetTags": [
"http-server"
],
"details": "tcp : 80",
"action": "allow"
}
],
"metadata": {
"recordCount": 7
}
}
GET /services/:service_code/:environment_name/firewallrules
Retrieve a list of all firewall rules in a given environment.
| Attributes | |
|---|---|
allowedArray[object] |
The list of ALLOW rules specified by this firewall. |
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
deniedArray[object] |
The list of DENY rules specified by this firewall. |
descriptionstring |
An optional description of this firewall rule. |
directionstring |
Direction of traffic to which this firewall applies, either INGRESS or EGRESS. The default is INGRESS. |
disabledboolean |
Denotes whether the firewall rule is disabled. When set to true, the firewall rule is not enforced and the network behaves as if it did not exist. |
idstring |
The unique identifier for the resource. |
kindstring |
Type of the resource. |
logConfigobject |
This field denotes the logging options for a particular firewall rule. If logging is enabled, logs will be exported to Stackdriver. |
namestring |
The display name of the firewall rule. |
networkstring |
URL of the network resource for this firewall rule. |
priorityinteger |
Priority for this rule. This is an integer between 0 and 65535, both inclusive. The default value is 1000. Relative priorities determine which rule takes effect if multiple rules apply. Lower values indicate higher priority. For example, a rule with priority 0 has higher precedence than a rule with priority 1. DENY rules take precedence over ALLOW rules if they have equal priority. Note that VPC networks have implied rules with a priority of 65535. To avoid conflicts with the implied rules, use a priority number less than 65535. |
selfLinkstring |
Server-defined URL for this resource. |
sourceRangesArray[string] |
Server-defined URL for the resource. |
targetTagsArray[string] |
A list of tags that controls which instances the firewall rule applies to. If targetTags are specified, then the firewall rule applies only to instances in the VPC network that have one of those tags. If no targetTags are specified, the firewall rule applies to all instances on the specified network. |
detailsstring |
Concatenation of the IP protocols followed by the port ranges. |
actionstring |
The firewall rule type: 'allow' (allow traffic) or 'deny' (deny traffic). |
Retrieve a firewall rule
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/firewallrules/4890726785951782638"
The above command returns a JSON structured like this:
{
"data": {
"allowed": [
{
"IPProtocol": "tcp",
"ports": [
"80"
]
}
],
"creationTimestamp": "2019-03-13T13:28:49.840-07:00",
"description": "",
"direction": "INGRESS",
"disabled": false,
"id": "4890726785951782638",
"kind": "compute#firewall",
"logConfig": {
"enable": false
},
"name": "default-allow-http",
"network": "https://www.googleapis.com/compute/v1/projects/flo-cmc-gcp-cay/global/networks/default",
"priority": 1000,
"selfLink": "https://www.googleapis.com/compute/v1/projects/flo-cmc-gcp-cay/global/firewalls/default-allow-http",
"sourceRanges": [
"0.0.0.0/0"
],
"targetTags": [
"http-server"
],
"details": "tcp : 80",
"action": "allow"
}
}
GET /services/:service_code/:environment_name/firewallrules/:id
Retrieve a firewall rules in a given environment.
| Attributes | |
|---|---|
allowedArray[object] |
The list of ALLOW rules specified by this firewall. |
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
deniedArray[object] |
The list of DENY rules specified by this firewall. |
descriptionstring |
An optional description of this firewall rule. |
directionstring |
Direction of traffic to which this firewall applies, either INGRESS or EGRESS. The default is INGRESS. |
disabledboolean |
Denotes whether the firewall rule is disabled. When set to true, the firewall rule is not enforced and the network behaves as if it did not exist. |
idstring |
The unique identifier for the resource. |
kindstring |
Type of the resource. |
logConfigobject |
This field denotes the logging options for a particular firewall rule. If logging is enabled, logs will be exported to Stackdriver. |
namestring |
The display name of the firewall rule. |
networkstring |
URL of the network resource for this firewall rule. |
priorityinteger |
Priority for this rule. This is an integer between 0 and 65535, both inclusive. The default value is 1000. Relative priorities determine which rule takes effect if multiple rules apply. Lower values indicate higher priority. For example, a rule with priority 0 has higher precedence than a rule with priority 1. DENY rules take precedence over ALLOW rules if they have equal priority. Note that VPC networks have implied rules with a priority of 65535. To avoid conflicts with the implied rules, use a priority number less than 65535. |
selfLinkstring |
Server-defined URL for this resource. |
sourceRangesArray[string] |
Server-defined URL for the resource. |
targetTagsArray[string] |
A list of tags that controls which instances the firewall rule applies to. If targetTags are specified, then the firewall rule applies only to instances in the VPC network that have one of those tags. If no targetTags are specified, the firewall rule applies to all instances on the specified network. |
detailsstring |
Concatenation of the IP protocols followed by the port ranges. |
actionstring |
The firewall rule type: 'allow' (allow traffic) or 'deny' (deny traffic). |
Create a firewall rule
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/firewallrule"
Request body example:
{
"action": "allow",
"all": true,
"direction": "INGRESS",
"name": "fw-rd-tuv",
"priority": 1000,
"range": "0.0.0.0/0",
}
POST /services/:service_code/:environment_name/firewallrule
Create a new firewall rule.
| Required | |
|---|---|
actionstring |
The firewall rule type: 'allow' (allow traffic) or 'deny' (deny traffic). |
directionstring |
Direction of traffic to which this firewall applies, either INGRESS or EGRESS. The default is INGRESS. |
namestring |
The display name of the firewall rule. |
prioritystring |
Priority for this rule. This is an integer between 0 and 65535, both inclusive. The default value is 1000. |
rangeArray[string] |
The source or destination range depending on the direction specified. The firewall rule applies only to traffic that has a source/destination IP address in these ranges. These ranges must be expressed in CIDR format. |
| Optional | |
|---|---|
allboolean |
Specifies if the firewall rule is an allow all or deny all rule. |
tcpPortsArray[string] |
The tcp ports on which to apply the rule. These must be in the range [0, 65535). |
udpPortsArray[string] |
The udp ports on which to apply the rule. These must be in the range [0, 65535). |
protocolsArray[string] |
Supported protocols are: icmp, esp, ah, sctp, ipip or a valid decimal IP protocol number. |
Delete a firewall rule
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/firewallrule/4890726785951782638"
DELETE /services/:service_code/:environment_name/firewallrule/:id
Delete an existing firewall rule.
External IPs
External IP address to an instance or a forwarding rule if you need to communicate with the Internet, with resources in another network, or need to communicate with a resource outside of Compute Engine.
List external IPs
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/externalips"
The above command returns a JSON structured like this:
{
"data": [
{
"address": "35.203.89.240",
"prefixLength": 0,
"status": "IN_USE",
"region": "https://www.googleapis.com/compute/v1/projects/test-env-qyu/zones/northamerica-northeast1-a",
"users": [
"https://www.googleapis.com/compute/v1/projects/test-env-qyu/zones/northamerica-northeast1-a/instances/i-root-fjt"
],
"shortUsers": [
"i-root-fjt"
],
"shortRegion": "northamerica-northeast1",
"type": "EPHEMERAL"
},
{
"id": "5737719067147816064",
"creationTimestamp": "2019-06-06T13:07:11.430-07:00",
"name": "address1",
"description": "",
"address": "35.232.24.253",
"prefixLength": 0,
"status": "RESERVED",
"region": "https://www.googleapis.com/compute/v1/projects/test-env-qyu/regions/us-central1",
"selfLink": "https://www.googleapis.com/compute/v1/projects/test-env-qyu/regions/us-central1/addresses/address1",
"networkTier": "PREMIUM",
"addressType": "EXTERNAL",
"kind": "compute#address",
"shortRegion": "us-central1",
"type": "STATIC"
}
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/externalips
Retrieve a list of all external IPs in a given environment.
| Attributes | |
|---|---|
idUUID |
Unique identifier for this ressource. Only present for static IPs. |
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
namestring |
The display name of the address. |
descriptionstring |
An optional description of the address. |
addressstring |
The IP address. |
prefixLengthnumber |
The prefix length if the resource reprensents an IP range. |
statusstring |
The status of the external IP address. One of the following: IN_USE, RESERVED, RESERVING. |
regionstring |
The URL of the region where the regional address resides. |
selfLinkstring |
Server-defined URL for this resource. |
usersArray[string] |
Links to the instances the IP address is attached to. |
networkTier*string |
Network tier used to configure that address. One of PREMIUM or STANDARD. Defaulted to PREMIER. |
addressTypestring |
The type of address to reserve, either INTERNAL or EXTERNAL. We only list EXTERNAL addresses. |
kindstring |
Type of the resource. Always compute#address for addresses. |
shortUsersArray[string] |
The names of the instances the IP address is attached to. |
shortRegionstring |
A short version of the region name. |
typestring |
One of EPHEMERAL or STATIC. EPHEMERAL are linked to an instance and are released automatically when an instance is deleted. |
Retrieve a regional static IP address
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/externalips/8516891730356002156"
The above command returns a JSON structured like this:
{
"data": {
"id": "8516891730356002156",
"creationTimestamp": "2019-06-06T12:03:31.935-07:00",
"name": "address1",
"description": "",
"address": "35.203.23.132",
"prefixLength": 0,
"status": "IN_USE",
"region": "https://www.googleapis.com/compute/v1/projects/test-env-qyu/regions/northamerica-northeast1",
"selfLink": "https://www.googleapis.com/compute/v1/projects/test-env-qyu/regions/northamerica-northeast1/addresses/address1",
"users": [
"https://www.googleapis.com/compute/v1/projects/test-env-qyu/zones/northamerica-northeast1-a/instances/i-root-caf"
],
"networkTier": "PREMIUM",
"addressType": "EXTERNAL",
"kind": "compute#address",
"shortUsers": [
"i-root-caf"
],
"shortRegion": "northamerica-northeast1",
"type": "STATIC"
}
}
GET /services/:service_code/:environment_name/externalips/:id
Retrieve an external IP in a given environment. Only for static IPs.
| Attributes | |
|---|---|
idUUID |
Unique identifier for this ressource. Only present for static IPs. |
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
namestring |
The display name of the address. |
descriptionstring |
An optional description of the address. |
addressstring |
The IP address. |
prefixLengthnumber |
The prefix length if the resource reprensents an IP range. |
statusstring |
The status of the external IP address. One of the following: IN_USE, RESERVED, RESERVING. |
regionstring |
The URL of the region where the regional address resides. |
selfLinkstring |
Server-defined URL for this resource. |
usersArray[string] |
Links to the instances the IP address is attached to. |
networkTierstring |
Network tier used to configure that address. One of PREMIUM or STANDARD. Defaulted to PREMIER. |
addressTypestring |
The type of address to reserve, either INTERNAL or EXTERNAL. We only list EXTERNAL addresses. |
kindstring |
Type of the resource. Always compute#address for addresses. |
shortUsersArray[string] |
The names of the instances the IP address is attached to. |
shortRegionstring |
A short version of the region name. |
typestring |
One of EPHEMERAL or STATIC. EPHEMERAL are linked to an instance and are released automatically when an instance is deleted. |
Reserve a regional external IP
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/externalips?operation=reserve"
Request body example:
{
"name": "my-static-ip",
"shortRegion": "northamerica-northeast1",
"shortInstance": "my-instance-name"
}
POST /services/:service_code/:environment_name/externalips
Reserve a new external static IP in a given environment.
If shortInstance is provided, the IP will be reserved and attached to this instance.
| Required | |
|---|---|
namestring |
The display name of the external ip. |
shortRegionstring |
A short version of the region name. |
| Optional | |
|---|---|
shortInstancestring |
The instance name to attach the new external ip address to. |
Release a static IP address
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/externalips/8516891730356002156"
DELETE /services/:service_code/:environment_name/externalips/:id
Release an existing external IP. The external IP goes back to the reserved pool, and is available to be attached to another instance.
Routes
A route is a path that network traffic takes from an instance to other destinations. The destination can be inside a GCP network or outside.
List routes
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/routes"
The above command returns a JSON structured like this:
{
"data": [
{ "id": "6918030089270271318",
"creationTimestamp": "2020-05-21T08:52:26.010-07:00",
"name": "default-route-0f2f9d9f9910829a",
"description": "Default local route to the subnetwork 10.172.0.0/20.",
"network": "https://www.googleapis.com/compute/v1/projects/test-area/global/networks/default",
"destRange": "10.172.0.0/20",
"priority": 0,
"nextHopNetwork": "https://www.googleapis.com/compute/v1/projects/test-area/global/networks/default",
"selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/global/routes/default-route-0f2f9d9f9910829a",
"kind": "compute#route",
"networkName": "default"
}],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/routes
Retrieve a list of all routes in an environment.
| Attributes | |
|---|---|
idstring |
The route's id. |
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
namestring |
The route's name. |
descriptionstring |
An optional description of this resource. |
networkstring |
URL of the network to which this route is attached. |
destRangestring |
The route's address destination. |
priorityinteger |
Priority for this route. Number should be a positive integer. Priority is used to break ties when there is more than one matching route of maximum length. |
nextHopNetworkstring |
The next hop handles the matching packets for this route. It can be an instance, an IP address or the default internet gateway. |
selfLinkstring |
Server-defined URL for the resource. |
kindstring |
Type of the resource. |
networkNamestring |
Name of the network to which this route is attached. |
Retrieve a route
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/routes/6918030089270271318"
The above command returns a JSON structured like this:
{
"data": {
"id": "6918030089270271318",
"creationTimestamp": "2020-05-21T08:52:26.010-07:00",
"name": "default-route-0f2f9d9f9910829a",
"description": "Default local route to the subnetwork 10.172.0.0/20.",
"network": "https://www.googleapis.com/compute/v1/projects/test-area/global/networks/default",
"destRange": "10.172.0.0/20",
"priority": 0,
"nextHopNetwork": "https://www.googleapis.com/compute/v1/projects/test-area/global/networks/default",
"selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/global/routes/default-route-0f2f9d9f9910829a",
"kind": "compute#route",
"networkName": "default"
}
}
GET /services/:service_code/:environment_name/routes/:id
Retrieve a route in a given environment.
| Attributes | |
|---|---|
idstring |
The route's id. |
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
namestring |
The route's name. |
descriptionstring |
An optional description of this resource. |
networkstring |
URL of the network to which this route is attached. |
destRangestring |
The route's address destination. |
priorityinteger |
Priority for this route. Number should be a positive integer. Priority is used to break ties when there is more than one matching route of maximum length. |
nextHopNetworkstring |
The next hop handles the matching packets for this route. It can be an instance, an IP address or the default internet gateway. |
selfLinkstring |
Server-defined URL for the resource. |
kindstring |
Type of the resource. |
networkNamestring |
Name of the network to which this route is attached. |
Routers
Cloud Router allows to programs custom dynamic routes and it scales with your network traffic. Cloud Router isn't a physical device that might cause a bottleneck. It can't be used by itself. But, it is required or recommended in the following cases:
- Required for Cloud NAT
- Required for Cloud Interconnect and High Availability (HA) VPN
- A recommended configuration option for Classic VPN
List Routers
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/routers"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "4369223640569972416",
"name": "c-router-failover",
"kind": "compute#router",
"shortRegion": "europe-west4",
"description": "Router specific to internal failover VPC",
"shortNetwork": "failover-vpc-network",
"network": "https://www.googleapis.com/compute/v1/projects/cmc-junniper-lab-ses/global/networks/failover-vpc-network",
....
....
},
{
"id": "0569972416436922364",
"name": "c-router-main",
"kind": "compute#router",
"shortRegion": "europe-west2",
"description": "Router specific to the main VPC",
"shortNetwork": "main-vpc-network",
"network": "https://www.googleapis.com/compute/v1/projects/cmc-junniper-lab-ses/global/networks/main-vpc-network",
},
.....
.....
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/routers
Retrieve a list of all cloud routers in a given environment.
| Attributes | |
|---|---|
dataArray[Object] |
List of cloud routers available in the current environment |
metadataArray |
A list of meta information about the response data. Contains recordCount which is an indication of the number of routers in the response |
Retrieve a Router
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/routers/0569972416436922364"
The above command returns a JSON structured like this:
{
"data": {
"id": "4369223640569972416",
"name": "c-router-failover",
"kind": "compute#router",
"shortRegion": "europe-west4",
"description": "Router specific to internal failover VPC",
"shortNetwork": "failover-vpc-network",
"network": "https://www.googleapis.com/compute/v1/projects/cmc-junniper-lab-ses/global/networks/failover-vpc-network",
"region": "https://www.googleapis.com/compute/v1/projects/cmc-junniper-lab-ses/regions/europe-west4",
"selfLink": "https://www.googleapis.com/compute/v1/projects/cmc-junniper-lab-ses/regions/europe-west4/routers/c-router-failover",
"bgp": {
"advertiseMode": "DEFAULT",
"asn": 65510
},
"bgpPeers": [
{
"advertiseMode": "DEFAULT",
"interfaceName": "if-failover-bgp-session",
"ipAddress": "169.254.11.1",
"name": "failover-bgp-session",
"peerAsn": 64999,
"peerIpAddress": "169.254.11.2"
}
],
"interfaces": [
{
"name": "if-failover-bgp-session",
"ipRange": "169.254.11.1/30",
"linkedVpnTunnel": "https://www.googleapis.com/compute/v1/projects/cmc-junniper-lab-ses/regions/europe-west4/vpnTunnels/failover-vpn-tunnel"
}
]
}
}
GET /services/:service_code/:environment_name/routers/:id
Retrieve a cloud router in a given environment.
| Attributes | |
|---|---|
idUUID |
Unique identifier for this resource. |
namestring |
The display name of the VPN gateway. |
kindstring |
The type of GCP compute resource. |
descriptionstring |
A user-friendly description about the router and its purpose. |
shortRegionstring |
The specific region in which the router resides in. |
shortNetworkstring |
The VPC network to which the router is attached to. |
networkstring |
The URI of the VPC network to which the touter is attached to. |
regionstring |
The URI of the region in which the router resided in. |
selfLinkstring |
Server-defined URL for the resource. |
bgpObject |
BGP information specific to this router. |
bgpPeersObject |
BGP information that is configured into the routing stack to establish BGP peering. (Includes: Peer ASN, Interface name, IP address) |
interfacesArray[Object] |
Router interfaces. Each interface contains either one linked resource or IP address and IP address range. |
Create a router
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/routers"
Request body example:
{
"name": "cmc-c-router",
"shortNetwork": "cmc-vpc",
"shortRegion": "us-central1",
"bgp": {
"asn": 65510
}
}
POST /services/:service_code/:environment_name/routers
Create a new router
| Required | |
|---|---|
namestring |
The display name of the router. |
shortRegionstring |
A short version of the region name. |
shortNetworkstring |
A shortened version of the network name that the router is attached to. |
bgp.asnstring |
The BGP Autonomous System Number (ASN) that is to be assigned to this router. Must be a valid ASN between 64512–65534. |
| Optional | |
|---|---|
regionstring |
Instead of the shortRegion, the long URI version of the region can also be provided. |
networkstring |
Instead of the shortNetwork, the long URI version of the network can also be provided. |
Add router interface(s)
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/routers/5333546534174463697?operation=addvpntunnelinterface"
Request body example:
{
"interfaces": [
{
"name": "if-cmc-srx-bgp-interface",
"ipRange": "169.254.13.1/30",
"linkedVpnTunnel": "https://www.googleapis.com/compute/v1/projects/cmc-junniper-lab-ses/regions/us-central1/vpnTunnels/cmc-srx-vpn-tunnel"
}
]
}
POST /services/:service_code/:environment_name/routers/:id?operation=addvpntunnelinterface
Add one or more interfaces associated to existing Vpn Tunnel(s).
| Required | |
|---|---|
interfacesArray |
An array of interfaces to be added to the selected router. |
interfaces[*].namestring |
The name of the interface on the router. |
interfaces[*].ipRangestring |
IP address and range of the interface. The IP range must be in the RFC3927 link-local IP address space. The value must be a CIDR-formatted string, for example: 169.254.0.1/30. |
interfaces[*].linkedVpnTunnelstring |
URI of the linked VPN tunnel, which must be in the same region as the router. |
Add BGP peer(s)
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/routers/5333546534174463697?operation=addbgppeer"
Request body example:
{
"bgpPeers": [
{
"name": "juniper-srx-bgp-5th-p2",
"interfaceName": "if-juniper-srx-bgp-3rd-exp",
"ipAddress": "169.254.13.1",
"peerIpAddress": "169.254.13.2",
"peerAsn": 64999
}
]
}
POST /services/:service_code/:environment_name/routers/:id?operation=addbgppeer
Add one or more BGP peers associated to existing router interface(s)
| Required | |
|---|---|
bgpPeersArray |
An array of BGP peers to be added to the selected router. |
bgpPeers[*].namestring |
The name of the BGP peer association. |
bgpPeers[*].interfaceNamestring |
The router interface through which this BGP peering will be realized. |
bgpPeers[*].ipAddressstring |
The router's IP address on the above interface for this BGP peering. Only IPv4 is supported. |
bgpPeers[*].peerIpAddressstring |
The peer IP address that the BGP peering will try to connect to. Only IPv4 is supported. |
bgpPeers[*].peerAsnstring |
Peer BGP Autonomous System Number (ASN). Each BGP interface may use a different value. |
Delete a Router
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/routers/5333546534174463697"
DELETE /services/:service_code/:environment_name/routers/:id
Delete an existing cloud router from the environment.
| Optional | |
|---|---|
selfLinkstring |
The partially qualified Google Cloud selfLink of this router. This should include the projectId, region and the router name delimited by the URL path separator. Ex: project-id/regions/<short-region>/routers/<router-name> |
VPN gateways
With Classic VPN, your on-premises hosts communicate through one or more IPsec VPN tunnels to Compute Engine Virtual Machine (VM) instances in your project's VPC networks.
List VPN gateways
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/vpngateways"
The above command returns a JSON structured like this:
{
"data": [
{
"creationTimestamp": "2019-08-27T06:37:19.149-07:00",
"description": "",
"region": "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1",
"network": "https://www.googleapis.com/compute/v1/projects/test-area/global/networks/default",
"status": "READY",
"selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/targetVpnGateways/test-vpn-gw",
"forwardingRules": [
"https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/forwardingRules/test-vpn-gw-rule-udp500",
"https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/forwardingRules/test-vpn-gw-rule-udp4500",
"https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/forwardingRules/test-vpn-gw-rule-esp"
],
"kind": "compute#targetVpnGateway",
"externalIp": {},
"tunnelsName": [],
"reserveStaticIP": false,
"id": "3112849056897469664",
"name": "test-vpn-gw",
"shortRegion": "us-central1"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/vpngateways
Retrieve a list of all VPN gateways in a given environment.
| Attributes | |
|---|---|
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
descriptionstring |
An optional description. |
externalIpObject |
The external IP attached to this VPN gateway. |
forwardingRulesArray |
List of the forwarding rules which are defined for this VPN gateway. |
idUUID |
Unique identifier for this resource. |
namestring |
The display name of the VPN gateway. |
networkstring |
URL of the network to which this VPN gateway is attached. |
regionstring |
The URL of the region where the VPN gateway is. |
statusstring |
The status of the VPN gateway. One of the following: READY, CREATING, FAILED and DELETING. |
selfLinkstring |
Server-defined URL for the resource. |
Retrieve a VPN gateway
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/vpngateways/3112849056897469664"
The above command returns a JSON structured like this:
{
"data": {
"creationTimestamp": "2019-08-27T06:37:19.149-07:00",
"description": "",
"region": "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1",
"network": "https://www.googleapis.com/compute/v1/projects/test-area/global/networks/default",
"status": "READY",
"selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/targetVpnGateways/test-vpn-gw",
"forwardingRules": [
"https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/forwardingRules/test-vpn-gw-rule-udp500",
"https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/forwardingRules/test-vpn-gw-rule-udp4500",
"https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/forwardingRules/test-vpn-gw-rule-esp"
],
"kind": "compute#targetVpnGateway",
"externalIp": {},
"tunnelsName": [],
"reserveStaticIP": false,
"id": "3112849056897469664",
"name": "test-vpn-gw",
"shortRegion": "us-central1"
}
}
GET /services/:service_code/:environment_name/vpngateways/:id
Retrieve a VPN gateway in a given environment.
| Attributes | |
|---|---|
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
descriptionstring |
An optional description. |
externalIpObject |
The external IP attached to this VPN gateway. |
forwardingRulesArray |
List of the forwarding rules which are defined for this VPN gateway. |
idUUID |
Unique identifier for this resource. |
namestring |
The display name of the VPN gateway. |
networkstring |
URL of the network to which this VPN gateway is attached. |
regionstring |
The URL of the region where the VPN gateway is. |
statusstring |
The status of the VPN gateway. One of the following: READY, CREATING, FAILED and DELETING. |
selfLinkstring |
Server-defined URL for the resource. |
Create a VPN gateway
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/vpngateways"
Request body examples:
{
"name": "test-my-vpn-gw",
"description": "my VPN gateway",
"shortRegion": "us-east4",
"reserveStaticIP": true
}
{
"name": "test-other-vpn-gw",
"description": "my other VPN gateway",
"shortRegion": "us-east4",
"shortIP": "my-vpn-gw-ip"
}
POST /services/:service_code/:environment_name/vpngateways
Create a new Classic VPN gateway in a given environment.
| Required | |
|---|---|
namestring |
The display name of the VPN gateway. |
shortRegionstring |
A short version of the region name. |
| Optional | |
|---|---|
descriptionstring |
An optional description. |
shortIPstring |
The name of the external static IP to use for the VPN gateway. |
reserveStaticIPstring |
A flag to indicate if a new external static IP needs to be reserved for the VPN gateway. This option is mutually exclusive with shortIP. |
Delete VPN gateway
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/vpngateways/3112849056897469664"
The above command returns a JSON structured like this:
{
"externalIpToRelease": ["32.45.23.54"]
}
DELETE /services/:service_code/:environment_name/vpngateways/:id
Delete a Classic VPN gateway in a given environment.
| Optional | |
|---|---|
externalIpToReleaseArray |
A list with only one element specifying the IP address to release. |
VPN tunnels
With Classic VPN, your on-premises hosts communicate through one or more IPsec VPN tunnels to Compute Engine Virtual Machine (VM) instances in your project's VPC networks.
List VPN tunnels
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/vpntunnels"
The above command returns a JSON structured like this:
{
"data": [
{
"creationTimestamp": "2019-12-12T06:34:44.930-08:00",
"description": "",
"region": "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1",
"targetVpnGateway": "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/targetVpnGateways/test-vpn-gw",
"vpnGatewayInterface": 0,
"peerExternalGatewayInterface": 0,
"peerIp": "69.196.164.138",
"sharedSecret": "*************",
"sharedSecretHash": "AG9FPaFV_aT2jaIN4cdrnDunzHL8",
"status": "ESTABLISHED",
"selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/vpnTunnels/vt-epk",
"ikeVersion": 2,
"detailedStatus": "Tunnel is up and running.",
"localTrafficSelector": [
"10.128.0.0/20"
],
"remoteTrafficSelector": [
"10.177.132.0/22"
],
"kind": "compute#vpnTunnel",
"gcpVpnGateway": {},
"shortVpnGateway": "test-vpn-gw",
"shortNetwork": "test-vpc",
"address": "34.66.131.105",
"type": "CLASSIC",
"id": "8211895554244865771",
"name": "vt-test-epk",
"shortRegion": "us-central1"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/vpntunnels
Retrieve a list of all VPN tunnels in a given environment.
| Attributes | |
|---|---|
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
descriptionstring |
An optional description. |
idUUID |
Unique identifier for this resource. |
gcpVpnGatewayObject |
The VPN Gateway associated with this tunnel. |
ikeVersioninteger |
IKE protocol version to use when establishing the VPN tunnel with the peer VPN gateway. Acceptable IKE versions are 1 or 2. The default version is 2. |
localTrafficSelectorstring |
Local traffic selector to use when establishing the VPN tunnel with the peer VPN gateway. The value should be a CIDR formatted string. Only IPv4 is supported. By default it's the CIDR associated with the region in which the VPN gateway resides. |
namestring |
The display name of the address. |
peerIpstring |
IP address of the peer VPN gateway in another VPC. |
regionstring |
The URL of the region where the VPN tunnel is. |
remoteTrafficSelectorstring |
Remote traffic selectors to use when establishing the VPN tunnel with the peer VPN gateway. The value should be a CIDR formatted string. Only IPv4 is supported. The CIDR associated with the peerIp. |
sharedSecretstring |
Shared secret used to set the secure session between the Cloud VPN gateway and the peer VPN gateway. |
statusstring |
The status of the VPN tunnel. |
selfLinkstring |
Server-defined URL for the resource. |
targetVpnGatewaystring |
The URL of the Target VPN gateway with which this VPN tunnel is associated. |
shortVpnGatewaystring |
Name of the VPN gateway with which this VPN tunnel is associated. |
shortNetworkstring |
Name of the network with which this VPN tunnel is associated. |
shortRegionstring |
Name of the region with which the VPN gateway attached to the tunnel is located. |
typestring |
The type of this VPN Tunnel. Only CLASSIC is supported. |
Retrieve a VPN tunnel
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/vpntunnels/8211895554244865771"
The above command returns a JSON structured like this:
{
"data":{
"creationTimestamp": "2019-12-12T06:34:44.930-08:00",
"description": "",
"region": "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1",
"targetVpnGateway": "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/targetVpnGateways/test-vpn-gw",
"vpnGatewayInterface": 0,
"peerExternalGatewayInterface": 0,
"peerIp": "69.196.164.138",
"sharedSecret": "*************",
"sharedSecretHash": "AG9FPaFV_aT2jaIN4cdrnDunzHL8",
"status": "ESTABLISHED",
"selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/vpnTunnels/vt-epk",
"ikeVersion": 2,
"detailedStatus": "Tunnel is up and running.",
"localTrafficSelector": [
"10.128.0.0/20"
],
"remoteTrafficSelector": [
"10.177.132.0/22"
],
"kind": "compute#vpnTunnel",
"gcpVpnGateway": {},
"shortVpnGateway": "test-vpn-gw",
"shortNetwork": "test-vpc",
"address": "34.66.131.105",
"type": "CLASSIC",
"id": "8211895554244865771",
"name": "vt-test-epk",
"shortRegion": "us-central1"
}
}
GET /services/:service_code/:environment_name/vpntunnels/:id
Retrieve a VPN tunnel in a given environment.
| Attributes | |
|---|---|
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
descriptionstring |
An optional description. |
idUUID |
Unique identifier for this resource. |
gcpVpnGatewayObject |
The VPN Gateway associated with this tunnel. |
ikeVersioninteger |
IKE protocol version to use when establishing the VPN tunnel with the peer VPN gateway. Acceptable IKE versions are 1 or 2. The default version is 2. |
localTrafficSelectorstring |
Local traffic selector to use when establishing the VPN tunnel with the peer VPN gateway. The value should be a CIDR formatted string. Only IPv4 is supported. By default it's the CIDR associated with the region in which the VPN gateway resides. |
namestring |
The display name of the address. |
peerIpstring |
IP address of the peer VPN gateway in another VPC. |
regionstring |
The URL of the region where the VPN tunnel is. |
remoteTrafficSelectorstring |
Remote traffic selectors to use when establishing the VPN tunnel with the peer VPN gateway. The value should be a CIDR formatted string. Only IPv4 is supported. The CIDR associated with the peerIp. |
sharedSecretstring |
Shared secret used to set the secure session between the Cloud VPN gateway and the peer VPN gateway. |
statusstring |
The status of the VPN tunnel. |
selfLinkstring |
Server-defined URL for the resource. |
targetVpnGatewaystring |
The URL of the Target VPN gateway with which this VPN tunnel is associated. |
shortVpnGatewaystring |
Name of the VPN gateway with which this VPN tunnel is associated. |
shortNetworkstring |
Name of the network with which this VPN tunnel is associated. |
shortRegionstring |
Name of the region with which the VPN gateway attached to the tunnel is located. |
typestring |
The type of this VPN Tunnel. Only CLASSIC is supported. |
Create a VPN tunnel
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/vpntunnels"
Request body example:
{
"name": "test-my-vpn-tunnel",
"description": "my VPN tunnel",
"targetVpnGateway": "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/targetVpnGateways/test-vpn-gw",
"peerIP": "69.196.164.138",
"ikeVersion": 2,
"sharedSecret": "mysecret",
"remoteTrafficSelector": "10.128.0.0/20",
"localTrafficSelector": ""
}
POST /services/:service_code/:environment_name/vpntunnels
Create a new Classic VPN tunnel in a given environment.
| Required | |
|---|---|
namestring |
The display name of the VPN tunnel. |
ikeVersionstring |
KE protocol version to use when establishing the VPN tunnel with the peer VPN gateway. Acceptable IKE versions are 1 or 2. The default version is 2. |
peerIPstring |
The IP address of the Virtual Private Cloud (VPC) the tunnel will connect to. |
remoteTrafficSelectorstring |
Remote traffic selectors to use when establishing the VPN tunnel with the peer VPN gateway. The value should be a CIDR formatted string. |
sharedSecretstring |
TShared secret used to set the secure session between the Cloud VPN gateway and the peer VPN gateway. |
targetVpnGatewaystring |
URL of the Target VPN gateway with which this VPN tunnel is associated. |
| Optional | |
|---|---|
descriptionstring |
An optional description. |
localTrafficSelectorstring |
Local traffic selector to use when establishing the VPN tunnel with the peer VPN gateway. The value should be a CIDR formatted string. |
Delete VPN Tunnel
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/vpntunnels/8211895554244865771"
The above command returns a JSON structured like this:
{
"vpnGatewayToDelete": "3932849056897469665",
"gcpVpnGateway": {
"externalIpToRelease": ["32.45.23.54"]
}
}
DELETE /services/:service_code/:environment_name/vpntunnels/:id
Delete a Classic VPN tunnel in a given environment.
| Optional | |
|---|---|
vpnGatewayToDeletestring |
The ID of the VPN gateway to delete after deleting the VPN tunnel. |
gcpVpnGateway.externalIpToReleaseArray |
A list with only one element specifying the IP address to release. |
Subnets
Create and manage your subnets. Subnets belongs to a network.
List subnets
curl -X GET \
-H "mc-api-key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/subnetworks"
The above command returns a JSON structured like this:
{
"data": [
{
"creationTimestamp": "2020-05-28T07:20:17.315-07:00",
"fingerprint": "resource_fingerprint",
"gatewayAddress": "10.128.0.1",
"ipCidrRange": "10.128.0.0/20",
"kind": "compute#subnetwork",
"network": "https://www.googleapis.com/compute/v1/projects/test-area-oox/global/networks/default",
"privateIpGoogleAccess": false,
"region": "https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/us-central1",
"selfLink": "https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/us-central1/subnetworks/default",
"shortNetwork": "default",
"id": "resource_id",
"name": "default",
"shortRegion": "us-central1"
}],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/subnetworks
Retrieve a list of all subnets in a given environment.
| Attributes | |
|---|---|
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
fingerprintstring |
A base64-encoded string. A hash of the label's contents and used for optimistic locking. |
gatewayAddressstring |
Second address in the primary IP range for the subnet. |
ipCidrRangestring |
Primary IP address range for the following resources: VM instances, internal load balancers, and internal protocol forwarding. |
kindstring |
Type of the resource. |
networkstring |
Server-defined URL for the VPC network that contains the subnet. |
privateIpGoogleAccessstring |
Whether the Private Google Access is configured. |
regionArray[Disk] |
Server-defined URL for the region name. |
selfLinkstring |
Server-defined URL for this resource. |
shortNetworkstring |
Display name of the VPC network that contains the subnet. |
idUUID |
The id of the subnet. |
namestring |
The display name of the subnet. |
shortRegionstring |
A short version of the region name. |
Filters
GET /services/:service_code/:environment_name/subnetworks?network=:VPC-network-selflink
Retrieve a list of all networks in a given environment and [VPC-network].
Retrieve a subnet
curl -X GET \
-H "mc-api-key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/subnetworks/8841143494674098002"
The above command returns a JSON structured like this:
{
"data": {
"creationTimestamp": "2020-06-12T08:05:33.741-07:00",
"fingerprint": "resource_fingerprint",
"gatewayAddress": "10.128.0.1",
"ipCidrRange": "10.128.0.0/20",
"kind": "compute#subnetwork",
"network": "https://www.googleapis.com/compute/v1/projects/test-area-oox/global/networks/default",
"privateIpGoogleAccess": false,
"region": "https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/us-central1",
"selfLink": "https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/us-central1/subnetworks/default",
"shortNetwork": "default",
"id": "resource_id",
"name": "default",
"shortRegion": "us-central1"
}
}
GET /services/:service_code/:environment_name/subnetworks/:id
Retrieve information about a subnet.
| Attributes | |
|---|---|
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
fingerprintstring |
A base64-encoded string. A hash of the label's contents and used for optimistic locking. |
gatewayAddressstring |
Second address in the primary IP range for the subnet. |
ipCidrRangestring |
Primary IP address range for the following resources: VM instances, internal load balancers, and internal protocol forwarding. |
kindstring |
Type of the resource. |
networkstring |
Server-defined URL for the VPC network that contains the subnet. |
privateIpGoogleAccessstring |
Whether the Private Google Access is configured. |
regionArray[Disk] |
Server-defined URL for the region name. |
selfLinkstring |
Server-defined URL for this resource. |
shortNetworkstring |
Display name of the VPC network that contains the subnet. |
idUUID |
The id of the subnet. |
namestring |
The display name of the subnet. |
shortRegionstring |
A short version of the region name. |
Create a subnet
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/subnetworks"
Request body example:
{
"name": "my-subnet",
"shortRegion": "northamerica-northeast1",
"ipCidrRange": "10.0.0.0/9",
"network": "https://www.googleapis.com/compute/v1/projects/my-project/global/networks/my-network"
}
POST /services/:service_code/:environment_name/subnetworks
Create a new subnet
| Required | |
|---|---|
namestring |
The display name of the subnet. |
shortRegionstring |
A short version of the region name. |
networkstring |
The selflink of the network. |
ipCidrRangestring |
The CIDR IP range of the subnet. |
| Optional | |
|---|---|
descriptionstring |
Description of the subnet. |
Delete a subnet
curl -X DELETE \
-H "mc-api-key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/subnetworks/8841143494674098002"
DELETE /services/:service_code/:environment_name/subnetworks/:id
Delete an existing subnet
Load balancing
Load balancer
HTTP(S) load balancing can balance HTTP and HTTPS traffic across multiple backend instances, across multiple regions. Your entire app is available via a single global IP address, resulting in a simplified DNS setup. HTTP(S) load balancing is scalable, fault-tolerant, requires no pre-warming, and enables content-based load balancing. For HTTPS traffic, it provides SSL termination and load balancing.
List load balancers
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/loadbalancers"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "8268558443601303519",
"forwardingRules": [
"https://www.googleapis.com/compute/v1/projects/test-area/global/forwardingRules/gfr-test-cme",
"https://www.googleapis.com/compute/v1/projects/test-area/global/forwardingRules/gfr-test-qxq"
],
"targetProxies": [
"https://www.googleapis.com/compute/v1/projects/test-area/global/targetHttpProxies/tp-test-fkb",
"https://www.googleapis.com/compute/v1/projects/test-area/global/targetHttpsProxies/tp-test-rqi"
],
"urlMap": "https://www.googleapis.com/compute/v1/projects/test-area/global/urlMaps/um-test-dfr",
"backendServices": [
"https://www.googleapis.com/compute/v1/projects/test-area/global/backendServices/be-test-jik"
],
"name": "um-test-dfr"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/loadbalancers
Retrieve a list of all load balancers in a given environment.
| Attributes | |
|---|---|
backendServicesList |
The list of backends for this resource. |
forwardingRulesList |
The list of forwarding rules for this resource. |
idString |
The id of this resource, which should be the same id as corresponding Url Map. |
nameString |
The name of this resource. |
targetProxiesList |
The list of target proxies for this resource. |
urlMapString |
Server-defined URL for corresponding url map. |
Retrieve a load balancer
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/loadbalancers/8268558443601303519"
The above command returns a JSON structured like this:
{
"data": {
"id": "8268558443601303519",
"forwardingRules": [
"https://www.googleapis.com/compute/v1/projects/test-area/global/forwardingRules/gfr-test-cme",
"https://www.googleapis.com/compute/v1/projects/test-area/global/forwardingRules/gfr-test-qxq"
],
"targetProxies": [
"https://www.googleapis.com/compute/v1/projects/test-area/global/targetHttpProxies/tp-test-fkb",
"https://www.googleapis.com/compute/v1/projects/test-area/global/targetHttpsProxies/tp-test-rqi"
],
"urlMap": "https://www.googleapis.com/compute/v1/projects/test-area/global/urlMaps/um-test-dfr",
"backendServices": [
"https://www.googleapis.com/compute/v1/projects/test-area/global/backendServices/be-test-jik"
],
"name": "um-test-dfr"
}
}
GET /services/:service_code/:environment_name/loadbalancers/:id
Retrieve a load balancer in a given environment.
| Attributes | |
|---|---|
backendServicesList |
The list of backends for this resource. |
forwardingRulesList |
The list of forwarding rules for this resource. |
idString |
The id of this resource, which should be the same id as corresponding Url Map. |
nameString |
The name of this resource. |
targetProxiesList |
The list of target proxies for this resource. |
urlMapString |
Server-defined URL for corresponding url map. |
Create a load balancer
curl -X POST \
-H 'MC-Api-Key: your_api_key' \
-H "Content-Type: application/json" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/loadbalancers"
Request body examples:
// Creating loadbalancer with ephemeral IP
{
"name":"my-loadbalancer-name",
"shortBackend": "my-backend-backend",
"shortProtocol": "HTTP",
"shortPort": "80"
}
// Creating loadbalancer with existing IP
{
"name":"my-loadbalancer-name",
"shortBackend": "my-backend-backend",
"shortProtocol": "HTTP",
"shortPort": "80",
"shortIP": "my-ip-name",
}
// Creating loadbalancer with new static IP
{
"name":"my-loadbalancer-name",
"shortBackend": "my-backend-backend",
"shortProtocol": "HTTP",
"shortPort": "80",
"reserveStaticIP": true
}
// Creating loadbalancer with HTTPS protocol
{
...
"shortPort": "443",
"shortCertificate": "my-SSL-certificate"
}
POST /services/:service_code/:environment_name/loadbalancers
Create a new load balancer.
| Required | |
|---|---|
namestring |
The display name of the load balancer. |
shortBackendstring |
The existing backend serivce that will be attached to this load balancer. |
shortProtocolstring |
The protocol of this resource. |
shortPortstring |
The port number of this resource. |
| Optional | |
|---|---|
reserveStaticIPboolean |
If the value is false and if no shortIP is provided, an ephemeral external IP address will be assigned. If the value is true, a new static IP would be reserved and provided to the resource. |
shortIPstring |
The name of an existing global external IP address assigned to the frontend. This argument is only valid in conjunction with reserveStaticIP being false. If the value is false and shortIP is provided, then the existing external IP address will be assigned. If the value is true, a new external static IP will be reserved and assigned. |
shortCertificatestring |
The name of the SSL certificate that will be attached to the target proxy if HTTPS is selected. (Required if HTTPS is selected for shortProtocol) |
Delete a load balancer
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/loadbalancers/8268558443601303519"
The above command returns a JSON structured like this:
{
"shortBackendsToDelete": ["be-test-jik", "be-other-srd"],
"shortHealthChecksToDelete": ["hc-test-olp", "hc-other-kop"],
"shortSslCertificatesToDelete": ["sc-test-ert"]
}
DELETE /services/:service_code/:environment_name/loadbalancers/:id
Delete an existing load balancer.
| Optional | |
|---|---|
shortBackendsToDeleteList |
A list of backend services to delete. |
shortHealthChecksToDeleteList |
A list of health checks to delete. |
shortSslCertificatesToDeleteList |
A list of SSL certificates to delete. |
Forwarding rules
A forwarding rule and its corresponding IP address represent the frontend configuration of a load balancer.
List forwarding rules
curl -X GET \
-H 'MC-Api-key: your_api_key'
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/forwardingrules"
The above command returns a JSON structured like this:
{
"data": [
{
"creationTimestamp": "2019-10-22T15:23:35.006-07:00",
"description": "",
"IPAddress": "35.227.251.25",
"IPProtocol": "TCP",
"ipVersion": "IPV4",
"kind": "compute#forwardingRule",
"loadBalancingScheme": "EXTERNAL",
"networkTier": "PREMIUM",
"portRange": "80-80",
"selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/global/forwardingRules/my-forwarding-rule",
"target": "https://www.googleapis.com/compute/v1/projects/test-area/global/targetHttpProxies/my-target-proxy",
"shortTarget": "my-target-proxy",
"id": "4724455712741277576",
"name": "my-forwarding-rule"
}
],
"metadata": {
"recordCount": 1
}
}
GET /service/:service_code/:environment_name/forwardingrules
Retrieve a list of all forwarding rules.
| Attributes | |
|---|---|
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
description string |
An optional description of this resource. |
idstring |
The unique identifier for the resource. This identifier is defined by the server. |
IPAddressstring |
The IP address that this forwarding rule serves. |
IPProtocolstring |
The IP protocol to which this rule applies. The default protocol is TCP. |
ipVersionstring |
The IP version that will be used by this forwarding rule. The default IP version is IPV4. |
kindstring |
Type of the resource. |
loadBalancingSchemestring |
Specifies the forwarding rule type. The default value is EXTERNAL. |
namestring |
Name of the resource. Provided by the client when the resource is created. |
networkTierstring |
This signifies the networking tier used for configuring this load balancer. |
portRangestring |
The destination ports that this forwarding rule forwards packets with. |
selfLinkstring |
Server-defined URL for this resource. |
shortTargetstring |
The name of the target resource. |
targetstring |
The URL of the target resource to receive the matched traffic. |
Retrieve a forwarding rule
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/forwardingrules/4724455712741277576"
The above command returns a JSON structured like this:
{
"data": {
"creationTimestamp": "2019-10-22T15:23:35.006-07:00",
"description": "",
"IPAddress": "35.227.251.25",
"IPProtocol": "TCP",
"ipVersion": "IPV4",
"kind": "compute#forwardingRule",
"loadBalancingScheme": "EXTERNAL",
"networkTier": "PREMIUM",
"portRange": "80-80",
"selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/global/forwardingRules/my-forwarding-rule",
"target": "https://www.googleapis.com/compute/v1/projects/test-area/global/targetHttpProxies/my-target-proxy",
"shortTarget": "my-target-proxy",
"id": "4724455712741277576",
"name": "my-forwarding-rule"
}
}
GET /services/:service_code/:environment_name/forwardingrules/:id
Retrieve a forwarding rule in a given environment.
| Attributes | |
|---|---|
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
description string |
An optional description of this resource. |
idstring |
The unique identifier for the resource. This identifier is defined by the server. |
IPAddressstring |
The IP address that this forwarding rule serves. |
IPProtocolstring |
The IP protocol to which this rule applies. The default protocol is TCP. |
ipVersionstring |
The IP version that will be used by this forwarding rule. The default IP version is IPV4. |
kindstring |
Type of the resource. |
loadBalancingSchemestring |
Specifies the forwarding rule type. The default value is EXTERNAL. |
namestring |
Name of the resource. Provided by the client when the resource is created. |
networkTierstring |
This signifies the networking tier used for configuring this load balancer. |
portRangestring |
The destination ports that this forwarding rule forwards packets with. |
selfLinkstring |
Server-defined URL for this resource. |
shortTargetstring |
The name of the target resource. |
targetstring |
The URL of the target resource to receive the matched traffic. |
Create a forwarding rule
curl -X POST \
-H 'MC-Api-Key: your_api_key' \
-H "Content-Type: application/json" \
-d "request _body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/forwardingrules"
Request body examples:
// Creating a forwarding rule with ephemeral IP
{
"portRange": "80",
"name": "my-forwarding-name",
"shortTarget": "my-target-proxy"
}
// Creating a forwarding rule with new static IP
{
"portRange": "80",
"name": "my-forwarding-name",
"shortTarget": "my-target-proxy",
"reserveStaticIP": true
}
// Creating a forwarding rule with ephemeral IP
{
"portRange": "80",
"name": "my-forwarding-name",
"shortTarget": "my-target-proxy",
"shortIPAddress": "my-IP-address"
}
POST /services/:service_code/:environment_name/forwardingrules
Create a new forwarding rule.
| Required | |
|---|---|
namestring |
The display name of the forwarding rule. |
portRangestring |
The port which will be allocated to the forwarding rule. Supported ports are: 80 or 8080 (HTTP) and 443 (HTTPS). |
shortTargetstring |
The name of the target resource. |
| Optional | |
|---|---|
descriptionstring |
Description of the forwarding rule. |
reserveStaticIPboolean |
If the value is false and if no shortIPAddress is provided, an ephemeral external IP address will be assigned. |
shortIPAddressstring |
The name of an existing global external IP address assigned to the rule. This argument is only valid in conjunction with reserveStaticIP being false. If the value is false and shortIPAddress is provided, then the existing external IP address will be assigned. If the value is true, a new external static IP will be reserved and assigned. |
Delete a forwarding rule
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/forwardingrules/5459493658413662148"
DELETE /services/:service_code/:environment_name/forwardingrules/:id
Destroy an existing global forwarding rule.
Target proxies
Target proxies route incoming request to either a URL map (HTTP(S) load balancing) or a backend service (SSL/TCP load balancing).
List target proxies
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/targetproxies"
The above command returns a JSON structured like this:
{
"data": [
{
"creationTimestamp": "2019-10-01T08:52:41.664-07:00",
"id": "2137054791002409126",
"kind": "compute#targetHttpProxy",
"name": "targetProxyName",
"selfLink": "https://www.googleapis.com/compute/v1/projects/test-area-oox/global/targetHttpProxies/targetProxyName",
"urlMap": "https://www.googleapis.com/compute/v1/projects/test-area-oox/global/urlMaps/urlMapName",
"type": "HTTP",
"shortUrlMap": "urlMapName"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/targetproxies
Retrieve a list of all target proxies in an environment.
| Attributes | |
|---|---|
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
idUUID |
The id of the backend service. |
kindstring |
Type of the resource. Either compute#targetHttpProxy or compute#targetHttpsProxy for target proxies. |
namestring |
Name of the resource. |
selfLinkstring |
Server-defined URL for the resource. |
shortUrlMapstring |
A short version of the URL map name. |
shortCertificatesstring |
A short version of the SSL certificate name. |
typeenum |
A short version of the kind of resource. Either HTTP or HTTPS. |
urlMapstring |
URL to the UrlMap resource that defines the mapping from URL to the BackendService. |
Retrieve a target proxy
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/targetproxies/2137054791002409126"
The above command returns a JSON structured like this:
{
"data": {
"creationTimestamp": "2019-10-01T08:52:41.664-07:00",
"id": "2137054791002409126",
"kind": "compute#targetHttpsProxy",
"name": "targetProxyName",
"selfLink": "https://www.googleapis.com/compute/v1/projects/test-area-oox/global/targetHttpsProxies/targetProxyName",
"sslCertificates": [
"https://www.googleapis.com/compute/v1/projects/test-area-oox/global/sslCertificates/sslCertificateName"
],
"type": "HTTPS",
"urlMap": "https://www.googleapis.com/compute/v1/projects/test-area-oox/global/urlMaps/urlMapName",
"shortUrlMap": "urlMapName",
"shortCertificates": "sslCertificateName"
}
}
GET /services/:service_code/:environment_name/targetproxies/:id
Retrieve a target proxy in an environment.
| Attributes | |
|---|---|
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
idUUID |
The id of the backend service. |
kindstring |
Type of the resource. Either compute#targetHttpProxy or compute#targetHttpsProxy for target proxies. |
namestring |
Name of the resource. |
selfLinkstring |
Server-defined URL for the resource. |
shortUrlMapstring |
A short version of the URL map name. |
shortCertificatesstring |
A short version of the SSL certificate name. |
typeenum |
A short version of the kind of resource. Either HTTP or HTTPS. |
urlMapstring |
URL to the UrlMap resource that defines the mapping from URL to the BackendService. |
Create a target proxy
# Example request: Specifying an existing URL map
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/targetProxies"
Request body examples:
// Specifying an existing URL map
{
"name": "targetProxyName",
"type": "HTTPS",
"shortUrlMap": "urlMapName",
"shortCertificates": "sslCertificateName"
}
// Specifying a backend service, a default URL map will be created automatically
{
"name": "targetProxyName",
"type": "HTTPS",
"shortBackend": "backendServicesName",
"shortCertificates": "sslCertificateName"
}
POST /services/:service_code/:environment_name/targetProxies
Create a new target proxy.
| Required | |
|---|---|
namestring |
Name of the resource. |
typeenum |
A short version of the kind of resource. |
shortBackendstring |
A short version of the backend service name. The shortBackend and shortUrlMap attributes are mutually exclusive. |
shortCertificatesstring |
A short version of the SSL certificate name. Specifying an SSL certificate is only required when creating an HTTPS target proxy. |
shortUrlMapstring |
A short version of the URL map name. The shortBackend and shortUrlMap attributes are mutually exclusive. |
Delete a target proxy
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/targetproxies/2137054791002409126"
DELETE /services/:service_code/:environment_name/targetproxies/:id
Delete an existing target proxy. A target proxy can only be deleted if it is not used in any urlMap.
Backend services
A backend service directs traffic to backends, such as instance groups.
List backend services
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/backendservices"
The above command returns a JSON structured like this:
{
"data": [
{
"affinityCookieTtlSec": 0,
"backends": [
{
"balancingMode": "UTILIZATION",
"capacityScaler": 1.0,
"description": "",
"group": "https://www.googleapis.com/compute/v1/projects/testAreaName/zones/us-central1-a/instanceGroups/instanceGroupName",
"maxUtilization": 0.8
}
],
"connectionDraining": {
"drainingTimeoutSec": 300
},
"creationTimestamp": "2019-09-23T12:57:58.039-07:00",
"description": "",
"enableCDN": false,
"fingerprint": "nH5X-L6Fovs=",
"healthChecks": [
"https://www.googleapis.com/compute/v1/projects/testAreaName/global/healthChecks/healthCheckName"
],
"kind": "compute#backendService",
"loadBalancingScheme": "EXTERNAL",
"port": 80,
"portName": "http",
"protocol": "HTTP",
"selfLink": "https://www.googleapis.com/compute/v1/projects/testAreaName/global/backendServices/backendServiceName",
"sessionAffinity": "NONE",
"timeoutSec": 30,
"shortHealthChecks": "healthCheckName",
"shortBackends": "instanceGroupName",
"id": "526709884866305321",
"name": "backendServiceName"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/backendservices
Retrieve a list of all backend services in an environment.
| Attributes | |
|---|---|
affinityCookieTtlSecnumber |
If set to 0, the cookie is non-persistent and lasts only until the end of the browser session (or equivalent). The maximum allowed value is one day (86,400). |
backendsobject |
The list of backends that serve this BackendService. |
connectionDrainingobject |
- |
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
descriptionstring |
An optional description of the resource. |
enableCDNboolean |
If true, enables Cloud CDN for the backend service. Only applicable if the loadBalancingScheme is EXTERNAL and the protocol is HTTP or HTTPS. |
fingerprintstring |
Fingerprint of this resource. A hash of the contents stored in this object. |
healthChecksstring |
The list of URLs to the HttpHealthCheck or HttpsHealthCheck resource for health checking this BackendService. Currently at most one health check can be specified. |
idUUID |
The id of the backend service. |
kindstring |
Type of the resource. Always compute#backendService for backend services. |
loadBalancingSchemeenum |
Indicates whether the backend service will be used with internal or external load balancing. Possible values are INTERNAL and EXTERNAL. |
namestring |
Name of the resource. |
portNamestring |
A named port on a backend instance group representing the port for communication to the backend VMs in that group. |
protocolenum |
The protocol this BackendService uses to communicate with backends. Possible values are HTTP or HTTPS. |
selfLinkstring |
Server-defined URL for the resource. |
sessionAffinityenum |
Type of session affinity to use. The default is NONE. |
shortBackendsstring |
A short version of the list of backends. |
shortHealthChecksstring |
A short version of the health checks. |
timeoutSecnumber |
The default is 30 seconds. |
Retrieve a backend service
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/backendservices"
The above command returns a JSON structured like this:
{
"data": {
"affinityCookieTtlSec": 0,
"backends": [
{
"balancingMode": "UTILIZATION",
"capacityScaler": 1.0,
"description": "",
"group": "https://www.googleapis.com/compute/v1/projects/testAreaName/zones/us-central1-a/instanceGroups/instanceGroupName",
"maxUtilization": 0.8
}
],
"connectionDraining": {
"drainingTimeoutSec": 300
},
"creationTimestamp": "2019-09-23T12:57:58.039-07:00",
"description": "",
"enableCDN": false,
"fingerprint": "nH5X-L6Fovs=",
"healthChecks": [
"https://www.googleapis.com/compute/v1/projects/testAreaName/global/healthChecks/healthCheckName"
],
"kind": "compute#backendService",
"loadBalancingScheme": "EXTERNAL",
"port": 80,
"portName": "http",
"protocol": "HTTP",
"selfLink": "https://www.googleapis.com/compute/v1/projects/testAreaName/global/backendServices/backendServiceName",
"sessionAffinity": "NONE",
"timeoutSec": 30,
"shortHealthChecks": "healthCheckName",
"shortBackends": "instanceGroupName",
"id": "526709884866305321",
"name": "backendServiceName"
}
}
GET /services/:service_code/:environment_name/backendservices/:id
Retrieve a backend service in an environment.
| Attributes | |
|---|---|
affinityCookieTtlSecnumber |
If set to 0, the cookie is non-persistent and lasts only until the end of the browser session (or equivalent). The maximum allowed value is one day (86,400). |
backendsobject |
The list of backends that serve this BackendService. |
connectionDrainingobject |
- |
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
descriptionstring |
An optional description of the resource. |
enableCDNboolean |
If true, enables Cloud CDN for the backend service. Only applicable if the loadBalancingScheme is EXTERNAL and the protocol is HTTP or HTTPS. |
fingerprintstring |
Fingerprint of this resource. A hash of the contents stored in this object. |
healthChecksstring |
The list of URLs to the HttpHealthCheck or HttpsHealthCheck resource for health checking this BackendService. Currently at most one health check can be specified. |
idUUID |
The id of the backend service. |
kindstring |
Type of the resource. Always compute#backendService for backend services. |
loadBalancingSchemeenum |
Indicates whether the backend service will be used with internal or external load balancing. Possible values are INTERNAL and EXTERNAL. |
namestring |
Name of the resource. |
portNamestring |
A named port on a backend instance group representing the port for communication to the backend VMs in that group. |
protocolenum |
The protocol this BackendService uses to communicate with backends. Possible values are HTTP or HTTPS. |
selfLinkstring |
Server-defined URL for the resource. |
sessionAffinityenum |
Type of session affinity to use. The default is NONE. |
shortBackendsstring |
A short version of the list of backends. |
shortHealthChecksstring |
A short version of the health checks. |
timeoutSecnumber |
The default is 30 seconds. |
Create backend service
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/backendservices"
Request body example:
{
"name": "my-instance",
"shortRegion": "northamerica-northeast1",
"shortZone": "northamerica-northeast1-a",
"bootDiskType": "pd-standard",
"bootDiskSizeInGb": "10",
"cpuCount": "2",
"memoryInGB": "4.5",
"osImageSelfLink": "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-9-stretch-v20190514",
"externalIp": {
"id": "3645738160550100933"
}
}
POST /services/:service_code/:environment_name/backendservices
Create a new backend service.
| Required | |
|---|---|
namestring |
The display name of the backend service. |
shortBackendsstring |
A short version of the list of backends. |
shortHealthChecksstring |
A short version of the health checks. |
Delete a backend service
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/backendservices/2570199154720991429"
DELETE /services/:service_code/:environment_name/backendservices/:id
Delete an existing backend service. A backend service can only be deleted if it is not used in any urlMap.
SSL Certificates
Represents an SSL Certificate resource.
List ssl certificate
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/sslcertificates"
The above command returns a JSON structured like this:
{
"data": [
{
"certificate": "-----BEGIN CERTIFICATE-----
(encoded certificate body in here)
-----END CERTIFICATE-----",
"creationTimestamp": "2019-10-02T10:36:39.138-07:00",
"id": "6911678730387654321",
"kind": "compute#sslCertificate",
"name": "ssl-root-ozv",
"selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/global/sslCertificates/ssl-root-ozv",
"domain": "ApiDocsDomain",
"organization": "ApiDocsOrg",
"validUntil": "2020-09-30",
"validFrom": "2019-10-01",
"issuerName": "ApiDocs",
"uploadDate": "2019-10-02"
},
{
"certificate": "-----BEGIN CERTIFICATE-----
(encoded certificate body in here)
-----END CERTIFICATE-----",
"creationTimestamp": "2019-10-01T13:33:36.409-07:00",
"id": "2973924929495238351",
"kind": "compute#sslCertificate",
"name": "ssl-root-tcs",
"selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/global/sslCertificates/ssl-root-tcs",
"domain": "ApiDocsDomain",
"organization": "ApiDocsOrg",
"validUntil": "2020-09-30",
"validFrom": "2019-10-01",
"issuerName": "ApiDocs",
"uploadDate": "2019-10-01"
},
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/sslcertificates
Retrieve a list of all ssl certificates in an environment.
| Attributes | |
|---|---|
certificateString |
A local certificate file. The certificate must be in PEM format. The certificate chain must be no greater than 5 certs long. The chain must include at least one intermediate cert. |
creationTimestampString |
Creation timestamp in RFC3339 text format. |
domainstring |
The domain name on certificate. |
idString |
The id of the ssl certificate. |
issuerNamestring |
Name of the issuer. |
kindstring |
Type of the resource. Always compute#sslCertificate for ssl certificate. |
namestring |
Name of the resource. |
organizationstring |
The organization to which certificate belongs. |
selfLinkstring |
Server-defined URL for the resource. |
uploadDatestring |
Date when certificate is uploaded. |
validFromstring |
Date from when certificate is valid. |
validUntilstring |
Date up until which certificate is valid. |
Retrieve a ssl certificate
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/sslcertificates/6911678730334723784"
The above command returns a JSON structured like this:
{
"data": {
"certificate": "-----BEGIN CERTIFICATE-----
(encoded certificate body in here)
-----END CERTIFICATE-----",
"creationTimestamp": "2019-10-02T10:36:39.138-07:00",
"id": "6911678730334723784",
"kind": "compute#sslCertificate",
"name": "ssl-root-ozv",
"selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/global/sslCertificates/ssl-root-ozv",
"domain": "ApiDocsDomain",
"organization": "ApiDocsOrg",
"validUntil": "2020-09-30",
"validFrom": "2019-10-01",
"issuerName": "ApiDocs",
"uploadDate": "2019-10-02"
}
}
GET /services/:service_code/:environment_name/sslcertificates/:id
Retrieve a ssl certificate in an environment.
| Attributes | |
|---|---|
certificateString |
A local certificate file. The certificate must be in PEM format. The certificate chain must be no greater than 5 certs long. The chain must include at least one intermediate cert. |
creationTimestampString |
Creation timestamp in RFC3339 text format. |
domainstring |
The domain name on certificate. |
idString |
The id of the ssl certificate. |
issuerNamestring |
Name of the issuer. |
kindstring |
Type of the resource. Always compute#sslCertificate for ssl certificate. |
namestring |
Name of the resource. |
organizationstring |
The organization to which certificate belongs. |
selfLinkstring |
Server-defined URL for the resource. |
uploadDatestring |
Date when certificate is uploaded. |
validFromstring |
Date from when certificate is valid. |
validUntilstring |
Date up until which certificate is valid. |
Create ssl certificate
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/sslcertificates"
Request body example:
{
"name": "ssl-root-rny",
"privateKey": "-----BEGIN RSA PRIVATE KEY-----
(encoded private key body in here)
-----END RSA PRIVATE KEY-----",
"certificate": "-----BEGIN CERTIFICATE-----
(encoded certificate body in here)
-----END CERTIFICATE-----",
"chainCertificate": "-----BEGIN CERTIFICATE-----
(encoded chain certificate body in here)
-----END CERTIFICATE-----",
"description": "Api docs demo certificate"
}
POST /services/:service_code/:environment_name/sslcertificates
Create a new ssl certificate.
| Required | |
|---|---|
certificatestring |
Public key certificate in PEM format. |
chainCertificatestring |
Chain certificates in PEM format, if there are any. Also total number of certificates, including main certificate cannot be more than 5. |
descriptionstring |
A short description of this certificate. |
namestring |
The display name of the ssl certificate. |
privateKeystring |
The privateKey associated to certificate in PEM format. |
Delete a ssl certificate
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/sslcertificates/2973924929495212345"
DELETE /services/:service_code/:environment_name/sslcertificates/:id
Delete an existing SSL certificate. SSL certificate can only be deleted if it is not used in any target proxy.
Kubernetes
Clusters
List your Kubernetes clusters.
List clusters
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/clusters"
The above command returns a JSON structured like this:
{
"data": [
{
"status": "RUNNING",
"nodeCount": 3,
"endpoint": "104.197.118.234",
"location": "us-central1-a",
"creationTimestamp": "2019-07-08T18:45:16+00:00",
"caCert": "LS0tLS1CRUdJTiBD...",
"addressRange": "10.4.0.0/14",
"networkName": "default",
"subnetName": "default",
"currentMasterVersion": "1.15.12-gke.20",
"cpuCount": 12,
"memoryInGB": 24.00,
"labels": {
"key1": "value1"
},
"nodePoolMachineTypes": {
"e2-medium": 1,
},
"id": "projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1",
"name": "standard-cluster-1"
},
{
"status": "RUNNING",
"nodeCount": 1,
"endpoint": "34.66.215.161",
"location": "us-central1-a",
"creationTimestamp": "2019-07-08T14:59:19+00:00",
"caCert": "LS0tLS1CRUdJS0K...",
"addressRange": "10.44.0.0/14",
"networkName": "default",
"subnetName": "default",
"currentMasterVersion": "1.15.12-gke.20",
"cpuCount": 6,
"memoryInGB": 12.00,
"labels": {},
"nodePoolMachineTypes": {
"e2-custom-2-1024": 3
},
"id": "projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/your-first-cluster-1",
"name": "your-first-cluster-1",
}
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/clusters
| Attributes | |
|---|---|
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
nodeCountnumber |
Number of nodes in the cluster. |
endpointstring |
The IP address of the cluster's master node. All interactions with the Kubernetes API are done through the master node. |
location string |
The zone or region in which the cluster is running. For regional clusters, your cluster nodes may span multiple zones within the region. |
status string |
The status of the cluster. |
caCert string |
The base64 encoded certificate authority certificate for the cluster. |
addressRange string |
The IP address range of the container pods in this cluster, in CIDR notation (e.g. 10.96.0.0/14). |
networkName string |
The name of the Google Compute Engine network to which the cluster is connected. |
subnetName string |
The name of the Google Compute Engine subnetwork to which the cluster is connected. |
currentMasterVersion string |
The current software version of the master endpoint. |
cpuCount int |
The sum of CPU cores of all compute instances of the cluster. |
memoryInGB double |
The sum of memory allocated for all compute instances of the cluster. |
labels Map |
The resource labels for the cluster to use to annotate any related Google Compute Engine resources. |
nodePoolMachineTypes Map |
The machine type of the nodepools of the cluster, and the number of machines with that type for the cluster. |
id string |
The cluster is uniquely identified by the project name, location and cluster name. |
name string |
The name of the cluster. |
Retrieve a cluster
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/clusters/standard-cluster-1/projects/testarea-ugx/locations/us-central1-a/clusters/standard-cluster-1"
The above command returns a JSON structured like this:
{
"data": {
"status": "RUNNING",
"nodeCount": 3,
"endpoint": "104.197.118.234",
"location": "us-central1-a",
"creationTimestamp": "2019-07-08T18:45:16+00:00",
"caCert": "LS0tLS1CRUdJTiBD...",
"addressRange": "10.4.0.0/14",
"networkName": "default",
"subnetName": "default",
"currentMasterVersion": "1.15.12-gke.20",
"cpuCount": 12,
"memoryInGB": 24.00,
"labels": {
"key1": "value1"
},
"nodePoolMachineTypes": {
"e2-medium": 1,
},
"id": "projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1",
"name": "standard-cluster-1"
}
}
GET /services/:service_code/:environment_name/clusters/:cluster_id
| Attributes | |
|---|---|
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
nodeCountnumber |
Number of nodes in the cluster. |
endpointstring |
The IP address of the cluster's master node. All interactions with the Kubernetes API are done through the master node. |
location string |
The zone or region in which the cluster is running. For regional clusters, your cluster nodes may span multiple zones within the region. |
status string |
The status of the cluster. |
caCert string |
The base64 encoded certificate authority certificate for the cluster. |
addressRange string |
The IP address range of the container pods in this cluster, in CIDR notation (e.g. 10.96.0.0/14). |
networkName string |
The name of the Google Compute Engine network to which the cluster is connected. |
subnetName string |
The name of the Google Compute Engine subnetwork to which the cluster is connected. |
currentMasterVersion string |
The current software version of the master endpoint. |
cpuCount int |
The sum of CPU cores of all compute instances of the cluster. |
memoryInGB double |
The sum of memory allocated for all compute instances of the cluster. |
labels Map |
The resource labels for the cluster to use to annotate any related Google Compute Engine resources. |
nodePoolMachineTypes Map |
The machine type of the nodepools of the cluster, and the number of machines with that type for the cluster. |
id string |
The cluster is uniquely identified by the project name, location and cluster name. |
name string |
The name of the cluster. |
caCert string |
The base64 encoded certificate authority certificate for the cluster. |
Create a cluster
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/clusters"
Request body examples:
// Create a cluster
{
"name": "my-cluster",
"shortRegion": "northamerica-northeast1",
"shortZone": "northamerica-northeast1-a",
"currentMasterVersion": "1.17.12-gke.1501",
"nodeCount":"3",
"nodeType":"e2-highcpu-16",
"networkName": "default",
"subnetName": "default"
}
POST /services/:service_code/:environment_name/clusters
Create a new cluster.
| Required | |
|---|---|
namestring |
The display name of the cluster. |
shortRegionstring |
A short version of the region name. |
shortZonestring |
A short version of the zone name. |
currentMasterVersionstring |
The version of GKE used for this cluster. |
nodeCount string |
The number of nodes in the primary node pool of this cluster. This must be greater than 0. |
nodeTypestring |
The machine types of the nodes in the default node pool of this cluster. |
networkNamestring |
The network that the Kubernetes cluster is in. |
subnetNamestring |
Subnetwork to which the cluster will belong. The subnetwork specified must belong the network specified. |
Delete a cluster
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/clusters/projects/cmc-test-area-ugx/locations/us-central1-c/clusters/cluster-1"
DELETE /services/:service_code/:environment_name/clusters/:id
Delete a cluster. A cluster can only be deleted if it is in RUNNING or ERROR state.
The above command returns a JSON structured like this:
{
"taskId": "3e4d4466-ce4b-404b-ada5-ee5a3fb76f4e",
"taskStatus": "PENDING"
}
Namespaces
List namespaces
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/namespaces?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "default",
"metadata": {},
"spec": {},
"status": {}
}
],
"metadata": {
"recordCount": 4
}
}
GET /services/:service_code/:environment_name/namespaces?cluster_id=:cluster_id
Retrieve a list of all namespaces in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the namespaces. |
| Attributes | |
|---|---|
id string |
The id of the namespace. |
apiVersion string |
APIVersion defines the versioned schema of this representation of a namespace object |
metadata object |
The metadata of the namespace |
specobject |
The specification describes the attributes on a namespace. |
statusobject |
The status information of the namespace |
Get a namespace
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/namespaces/cert-manager?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "default",
"apiVersion": "v1",
"kind": "Namespace",
"metadata": {},
"spec": {},
"status": {}
}
}
GET /services/:service_code/:environment_name/namespaces/:id?cluster_id=:cluster_id
Retrieve a namespace and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the namespace. |
| Attributes | |
|---|---|
id string |
The id of the namespace. |
apiVersion string |
APIVersion defines the versioned schema of this representation of a namespace object |
metadata object |
The metadata of the namespace |
specobject |
The specification describes the attributes on a namespace. |
statusobject |
The status information of the namespace |
Create a namespace
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/namespaces?cluster_id=test-cluster"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Namespace",
"metadata": {
"name": "test-namespace"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/namespaces?cluster_id=:cluster_id
Create a namespace in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the namespace. |
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the namespace. |
metadata object |
The metadata of the namespace. |
metadata.name string |
The name of the namespace. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create namespace task. |
taskStatus string |
The status of the operation. |
Delete a namespace
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/namespaces/test-namespace?cluster_id=test-cluster"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/namespaces/:id?cluster_id=:cluster_id
Delete a namespace from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the namespace. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete namespaces task. |
taskStatus string |
The status of the operation. |
Workloads
Pods
List pods
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/pods?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "my-aerospike-0/default",
"metadata": {
"annotations": {
"checksum/config": "0e07919467cc16f2c07ac99d0036405deafa06f7d3b430215915470b3a6ca631"
},
"creationTimestamp": "2020-01-20T09:35:02.000-05:00",
"generateName": "my-aerospike-",
"labels": {
"app": "aerospike",
"controller-revision-hash": "my-aerospike-d9969496d",
"release": "my-aerospike",
"statefulset.kubernetes.io/pod-name": "my-aerospike-0"
},
"name": "my-aerospike-0",
"namespace": "default",
"ownerReferences": [
{
"apiVersion": "apps/v1",
"blockOwnerDeletion": true,
"controller": true,
"kind": "StatefulSet",
"name": "my-aerospike",
"uid": "0b00ea3d-3b92-11ea-935e-025000000001"
}
],
"resourceVersion": "95058",
"selfLink": "/api/v2/namespaces/default/pods/my-aerospike-0",
"uid": "0b055519-3b92-11ea-935e-025000000001"
},
"spec": {
"containers": [
{
"image": "aerospike/aerospike-server:4.5.0.5",
"imagePullPolicy": "IfNotPresent",
"name": "my-aerospike",
"ports": [
{
"containerPort": 3000,
"name": "clients",
"protocol": "TCP"
},
{
"containerPort": 3002,
"name": "mesh",
"protocol": "TCP"
},
{
"containerPort": 3003,
"name": "info",
"protocol": "TCP"
}
],
"readinessProbe": {
"failureThreshold": 3,
"initialDelaySeconds": 15,
"periodSeconds": 10,
"successThreshold": 1,
"tcpSocket": {
"port": 3000
},
"timeoutSeconds": 1
},
"resources": {},
"terminationMessagePath": "/dev/termination-log",
"terminationMessagePolicy": "File",
"volumeMounts": [
{
"mountPath": "/etc/aerospike",
"name": "config-volume"
},
{
"mountPath": "/var/run/secrets/kubernetes.io/serviceaccount",
"name": "default-token-64jnc",
"readOnly": true
}
]
}
],
"dnsPolicy": "ClusterFirst",
"enableServiceLinks": true,
"hostname": "my-aerospike-0",
"nodeName": "docker-desktop",
"priority": 0,
"restartPolicy": "Always",
"schedulerName": "default-scheduler",
"securityContext": {},
"serviceAccount": "default",
"serviceAccountName": "default",
"subdomain": "my-aerospike",
"terminationGracePeriodSeconds": 30,
"tolerations": [
{
"effect": "NoExecute",
"key": "node.kubernetes.io/not-ready",
"operator": "Exists",
"tolerationSeconds": 300
},
{
"effect": "NoExecute",
"key": "node.kubernetes.io/unreachable",
"operator": "Exists",
"tolerationSeconds": 300
}
],
"volumes": [
{
"configMap": {
"defaultMode": 420,
"items": [
{
"key": "aerospike.conf",
"path": "aerospike.conf"
}
],
"name": "my-aerospike"
},
"name": "config-volume"
},
{
"name": "default-token-64jnc",
"secret": {
"defaultMode": 420,
"secretName": "default-token-64jnc"
}
}
]
},
"status": {
"conditions": [
{
"lastTransitionTime": "2020-01-20T09:35:02.000-05:00",
"status": "True",
"type": "Initialized"
},
{
"lastTransitionTime": "2020-01-21T15:05:33.000-05:00",
"status": "True",
"type": "Ready"
},
{
"lastTransitionTime": "2020-01-21T15:05:33.000-05:00",
"status": "True",
"type": "ContainersReady"
},
{
"lastTransitionTime": "2020-01-20T09:35:02.000-05:00",
"status": "True",
"type": "PodScheduled"
}
],
"containerStatuses": [
{
"containerID": "docker://b45436d2978cb8e6186b22c24d3b819cabd00921a009b30c2599a935d0c69b49",
"image": "aerospike/aerospike-server:4.5.0.5",
"imageID": "docker-pullable://aerospike/aerospike-server@sha256:5bec98d46c8a521003e1c5b6f015713f2663384dd66916cca696e4e1c142c539",
"lastState": {
"terminated": {
"containerID": "docker://5e4b23c07269669f302c7c6a446399e59d553cf1a622094c1d3cc64b6f65a9e0",
"exitCode": 255,
"finishedAt": "2020-01-21T15:04:35.000-05:00",
"reason": "Error",
"startedAt": "2020-01-20T10:28:19.000-05:00"
}
},
"name": "my-aerospike",
"ready": true,
"restartCount": 2,
"state": {
"running": {
"startedAt": "2020-01-21T15:05:16.000-05:00"
}
}
}
],
"hostIP": "192.168.65.3",
"phase": "Running",
"podIP": "10.1.0.129",
"qosClass": "BestEffort",
"startTime": "2020-01-20T09:35:02.000-05:00"
}
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/pods?cluster_id=:cluster_id
Retrieve a list of all pods in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the pods. |
| Attributes | |
|---|---|
id string |
The id of the pod. |
metadata object |
The metadata of the pod. |
metadata.annotations map |
The annotations of the pod. |
metadata.creationTimestamp string |
The date of creation of the pod as a string. |
metadata.labels map |
The labels associated to the pod. |
metadata.name string |
The name of the pod. |
metadata.namespace string |
The namespace in which the pod is created. |
metadata.uid object |
The UUID of the pod. |
specobject |
The specification used to create and run the pod. |
spec.containerstring |
The name of the container running. |
statusobject |
The status information of the pod. |
status.phasestring |
The status of the pod. Possible statuses are Running, Pending, Succeeded, Unknown and Failed. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a pod
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/pods/my-aerospike-0/default?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "my-aerospike-0/default",
"metadata": {
"annotations": {
"checksum/config": "0e07919467cc16f2c07ac99d0036405deafa06f7d3b430215915470b3a6ca631"
},
"creationTimestamp": "2020-01-20T09:35:02.000-05:00",
"generateName": "my-aerospike-",
"labels": {
"app": "aerospike",
"controller-revision-hash": "my-aerospike-d9969496d",
"release": "my-aerospike",
"statefulset.kubernetes.io/pod-name": "my-aerospike-0"
},
"name": "my-aerospike-0",
"namespace": "default",
"ownerReferences": [
{
"apiVersion": "apps/v1",
"blockOwnerDeletion": true,
"controller": true,
"kind": "StatefulSet",
"name": "my-aerospike",
"uid": "0b00ea3d-3b92-11ea-935e-025000000001"
}
],
"resourceVersion": "95058",
"selfLink": "/api/v2/namespaces/default/pods/my-aerospike-0",
"uid": "0b055519-3b92-11ea-935e-025000000001"
},
"spec": {
"containers": [
{
"image": "aerospike/aerospike-server:4.5.0.5",
"imagePullPolicy": "IfNotPresent",
"name": "my-aerospike",
"ports": [
{
"containerPort": 3000,
"name": "clients",
"protocol": "TCP"
},
{
"containerPort": 3002,
"name": "mesh",
"protocol": "TCP"
},
{
"containerPort": 3003,
"name": "info",
"protocol": "TCP"
}
],
"readinessProbe": {
"failureThreshold": 3,
"initialDelaySeconds": 15,
"periodSeconds": 10,
"successThreshold": 1,
"tcpSocket": {
"port": 3000
},
"timeoutSeconds": 1
},
"resources": {},
"terminationMessagePath": "/dev/termination-log",
"terminationMessagePolicy": "File",
"volumeMounts": [
{
"mountPath": "/etc/aerospike",
"name": "config-volume"
},
{
"mountPath": "/var/run/secrets/kubernetes.io/serviceaccount",
"name": "default-token-64jnc",
"readOnly": true
}
]
}
],
"dnsPolicy": "ClusterFirst",
"enableServiceLinks": true,
"hostname": "my-aerospike-0",
"nodeName": "docker-desktop",
"priority": 0,
"restartPolicy": "Always",
"schedulerName": "default-scheduler",
"securityContext": {},
"serviceAccount": "default",
"serviceAccountName": "default",
"subdomain": "my-aerospike",
"terminationGracePeriodSeconds": 30,
"tolerations": [
{
"effect": "NoExecute",
"key": "node.kubernetes.io/not-ready",
"operator": "Exists",
"tolerationSeconds": 300
},
{
"effect": "NoExecute",
"key": "node.kubernetes.io/unreachable",
"operator": "Exists",
"tolerationSeconds": 300
}
],
"volumes": [
{
"configMap": {
"defaultMode": 420,
"items": [
{
"key": "aerospike.conf",
"path": "aerospike.conf"
}
],
"name": "my-aerospike"
},
"name": "config-volume"
},
{
"name": "default-token-64jnc",
"secret": {
"defaultMode": 420,
"secretName": "default-token-64jnc"
}
}
]
},
"status": {
"conditions": [
{
"lastTransitionTime": "2020-01-20T09:35:02.000-05:00",
"status": "True",
"type": "Initialized"
},
{
"lastTransitionTime": "2020-01-21T15:05:33.000-05:00",
"status": "True",
"type": "Ready"
},
{
"lastTransitionTime": "2020-01-21T15:05:33.000-05:00",
"status": "True",
"type": "ContainersReady"
},
{
"lastTransitionTime": "2020-01-20T09:35:02.000-05:00",
"status": "True",
"type": "PodScheduled"
}
],
"containerStatuses": [
{
"containerID": "docker://b45436d2978cb8e6186b22c24d3b819cabd00921a009b30c2599a935d0c69b49",
"image": "aerospike/aerospike-server:4.5.0.5",
"imageID": "docker-pullable://aerospike/aerospike-server@sha256:5bec98d46c8a521003e1c5b6f015713f2663384dd66916cca696e4e1c142c539",
"lastState": {
"terminated": {
"containerID": "docker://5e4b23c07269669f302c7c6a446399e59d553cf1a622094c1d3cc64b6f65a9e0",
"exitCode": 255,
"finishedAt": "2020-01-21T15:04:35.000-05:00",
"reason": "Error",
"startedAt": "2020-01-20T10:28:19.000-05:00"
}
},
"name": "my-aerospike",
"ready": true,
"restartCount": 2,
"state": {
"running": {
"startedAt": "2020-01-21T15:05:16.000-05:00"
}
}
}
],
"hostIP": "192.168.65.3",
"phase": "Running",
"podIP": "10.1.0.129",
"qosClass": "BestEffort",
"startTime": "2020-01-20T09:35:02.000-05:00"
}
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/pods/:id?cluster_id=:cluster_id
Retrieve a pod and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the pod. |
| Attributes | |
|---|---|
id string |
The id of the pod. |
metadata object |
The metadata of the pod. |
metadata.annotations map |
The annotations of the pod. |
metadata.creationTimestamp string |
The date of creation of the pod as a string. |
metadata.labels map |
The labels associated to the pod. |
metadata.name string |
The name of the pod. |
metadata.namespace string |
The namespace in which the pod is created. |
metadata.uid object |
The UUID of the pod. |
specobject |
The specification used to create and run the pod. |
spec.containerstring |
The name of the container running. |
statusobject |
The status information of the pod. |
status.phasestring |
The status of the pod. Possible statuses are Running, Pending, Succeeded, Unknown and Failed. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a pod
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/pods"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Pod",
"metadata": {
"name": "edgar-allen-pod",
"namespace": "default"
},
"spec": {
"containers": [
{
"image": "nginx",
"name": "nginx"
}
]
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/pods
Create a pod in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the pod |
metadata object |
The metadata of the pod |
metadata.name string |
The name of the pod |
specobject |
The specification used to create and run the pod |
spec.container.imagestring |
The docker image name |
spec.container.namestring |
The (unique) name of the container specified as a DNS_LABEL |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the pod is created |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create pod task. |
taskStatus string |
The status of the operation. |
Replace a pod
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/pods/edgar-allen-pod/default"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Pod",
"metadata": {
"name": "edgar-allen-pod",
"namespace": "default"
},
"spec": {
"containers": [
{
"image": "nginx",
"name": "nginx"
}
]
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/pods/:id
Replace a pod in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the pod. |
metadata object |
The metadata of the pod. |
metadata.name string |
The name of the pod. |
specobject |
The specification used to replace and run the pod. |
spec.container.imagestring |
The docker image name. |
spec.container.namestring |
The (unique) name of the container specified as a DNS_LABEL. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the pod is replaced. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace pod task. |
taskStatus string |
The status of the operation. |
Delete a pod
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/pods/my-aerospike-0/default?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/pods/:id?cluster_id=:cluster_id
Delete a pod from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to delete the pod. |
| Attributes | |
|---|---|
taskId string |
The task id related to the delete pod task. |
taskStatus string |
The status of the operation. |
Deployments
List deployments
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/deployments?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "coredns/kube-system",
"deploymentStatus": "Progressing",
"readyRatio": "2/2",
"metadata": {},
"spec": {},
"status": {}
}
],
"metadata": {
"recordCount": 6
}
}
GET /services/:service_code/:environment_name/deployments?cluster_id=:cluster_id
Retrieve a list of all deployments in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the deployments. |
| Attributes | |
|---|---|
id string |
The id of the deployment |
metadata object |
The metadata of the deployment |
images object |
The container images within a deployment |
specobject |
The specification used to create and run the deployment |
readyRatio object |
The ready replicas to total replicas ratio of this deployment set |
deploymentStatusobject |
The status information of the deployment |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a deployment
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/deployments/coredns/kube-system?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "coredns/kube-system",
"deploymentStatus": "Progressing",
"readyRatio": "2/2",
"apiVersion": "apps/v1",
"kind": "Deployment",
"metadata": {},
"spec": {},
"status": {}
}
}
GET /services/:service_code/:environment_name/deployments/:id?cluster_id=:cluster_id
Retrieve a deployment and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the deployment. |
| Attributes | |
|---|---|
id string |
The id of the deployment |
metadata object |
The metadata of the deployment |
images object |
The container images within a deployment |
specobject |
The specification used to create and run the deployment |
readyRatio object |
The ready replicas to total replicas ratio of this deployment set |
deploymentStatusobject |
The status information of the deployment |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a deployment
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/deployments?cluster_id=a_cluster_id"
Content-Type: application/json
{
"apiVersion": "apps/v1",
"kind": "Deployment",
"metadata": {
"name": "api-test-deployment-name",
"namespace": "default"
},
"spec": {
"selector": {
"matchLabels": {
"app": "nginx"
}
},
"template": {
"metadata": {
"labels": {
"app": "nginx"
}
},
"spec": {
"containers": [
{
"name": "nginx",
"image": "nginx"
}
]
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/deployments?cluster_id=:cluster_id
Create a deployment in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the deployment. |
metadata object |
The metadata of the deployment. |
metadata.name string |
The name of the deployment. |
specobject |
The specification used to replace and run the deployment. |
spec.selectorobject |
The label query over the deployment's set of resources. |
spec.templateobject |
The data a deployment's pod should have when replaced. |
spec.specobject |
The specification used to replace and run the pod(s) within the deployment. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the deployment is replaced. |
spec.selector.matchLabelsobject |
The key value pairs retrieved by a label query from a deployment. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace deployment task. |
taskStatus string |
The status of the operation. |
Replace a deployment
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/deployments/deployment-name/default"
Content-Type: application/json
{
"apiVersion": "apps/v1",
"kind": "Deployment",
"metadata": {
"name": "deployment-name",
"namespace": "default"
},
"spec": {
"selector": {
"matchLabels": {
"app": "nginx"
}
},
"template": {
"metadata": {
"labels": {
"app": "nginx"
}
},
"spec": {
"containers": [
{
"name": "nginx",
"image": "nginx"
}
]
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/deployments/:id
Replace a deployment in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the deployment. |
metadata object |
The metadata of the deployment. |
metadata.name string |
The name of the deployment. |
specobject |
The specification used to create and run the deployment. |
spec.selectorobject |
The label query over the deployment's set of resources. |
spec.templateobject |
The data a deployment's pod should have when created. |
spec.specobject |
The specification used to create and run the pod(s) within the deployment. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the deployment is created. |
spec.selector.matchLabelsobject |
The key value pairs retrieved by a label query from a deployment. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create deployment task. |
taskStatus string |
The status of the operation. |
Delete a deployment
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/deployments/dex/auth?cluster_id=a_cluster_id?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/deployments/:id?cluster_id=:cluster_id
Delete a deployment from a given environment.
| Required Attributes | |
|---|---|
cluster_id string |
The id of the cluster in which to list the deployments. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete deployment task. |
taskStatus string |
The status of the operation. |
Daemon Sets
List daemon sets
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/daemonsets?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "kube-proxy/kube-system",
"readyRatio": "3/3",
"metadata": {},
"spec": {},
"status": {}
}
],
"metadata": {
"recordCount": 5
}
}
GET /services/:service_code/:environment_name/daemonsets?cluster_id=:cluster_id
Retrieve a list of all daemon sets in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the daemon sets. |
| Attributes | |
|---|---|
id string |
The id of the daemon set |
metadata object |
The metadata of the daemon set |
specobject |
The specification used to create and run the daemon set |
statusobject |
The status information of the daemon set |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a daemon set
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/daemonsets/test-aerospike/auth?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "kube-proxy/kube-system",
"readyRatio": "3/3",
"apiVersion": "apps/v1",
"kind": "DaemonSet",
"metadata": {},
"spec": {},
"status": {}
}
}
GET /services/:service_code/:environment_name/daemonsets/:id?cluster_id=:cluster_id
Retrieve a daemon set and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the daemon set. |
| Attributes | |
|---|---|
id string |
The id of the daemon set |
metadata object |
The metadata of the daemon set |
specobject |
The specification used to create and run the daemon set |
statusobject |
The status information of the daemon set |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a daemon set
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/daemonsets?cluster_id=a_cluster_id"
Content-Type: application/json
{
"apiVersion": "apps/v1",
"metadata": {
"name": "daemonset-name",
"namespace": "default"
},
"spec": {
"selector": {
"matchLabels": {
"name": "fluentd-elasticsearch"
}
},
"template": {
"metadata": {
"labels": {
"name": "fluentd-elasticsearch"
}
},
"spec": {
"containers": [
{
"name": "fluentd-elasticsearch",
"image": "quay.io/fluentd_elasticsearch/fluentd:v2.5.2"
}
]
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/daemonsets?cluster_id=:cluster_id
Create a daemon set in a given environment.
| Required Attributes | |
|---|---|
cluster_id string |
The id of the cluster in which to get the daemon set. |
apiVersion string |
The api version (versioned schema) of the daemon set |
metadata object |
The metadata of the daemon set |
metadata.name string |
The name of the daemon set |
specobject |
The specification used to create and run the daemon set |
spec.selectorobject |
The label query over the daemon set's resources |
spec.templateobject |
The data a daemon set's pod should have when created |
spec.specobject |
The specification used to create and run the pod(s) within the daemon set |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the daemon set is created |
spec.selector.matchLabelsobject |
The key value pairs retrieved by a label query from a daemon set |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create daemon set task. |
taskStatus string |
The status of the operation. |
Replace a daemon set
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/daemonsets/daemonset-name/default"
Content-Type: application/json
{
"apiVersion": "apps/v1",
"kind": "DaemonSet",
"metadata": {
"name": "daemonset-name",
"namespace": "default"
},
"spec": {
"selector": {
"matchLabels": {
"name": "fluentd-elasticsearch"
}
},
"template": {
"metadata": {
"labels": {
"name": "fluentd-elasticsearch"
}
},
"spec": {
"containers": [
{
"name": "fluentd-elasticsearch",
"image": "quay.io/fluentd_elasticsearch/fluentd:v2.5.2"
}
]
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/daemonsets/:id
Replace a daemon set in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the daemon set. |
metadata object |
The metadata of the daemon set. |
metadata.name string |
The name of the daemon set. |
specobject |
The specification used to replace and run the daemon set. |
spec.selectorobject |
The label query over the daemon set's resources. |
spec.templateobject |
The data a daemon set's pod should have when replaced. |
spec.specobject |
The specification used to create and run the pod(s) within the daemon set. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the daemon set is replaced. |
spec.selector.matchLabelsobject |
The key value pairs retrieved by a label query from a daemon set. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace daemon set task. |
taskStatus string |
The status of the operation. |
Delete a daemon set
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/daemonsets/nginx-ingress-controller/ingress-nginx?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/daemonsets/:id?cluster_id=:cluster_id
Delete a daemon set from a given environment.
| Required Attributes | |
|---|---|
cluster_id string |
The id of the cluster in which to get the daemon set. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete daemon set task. |
taskStatus string |
The status of the operation. |
Stateful Sets
List stateful sets
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/statefulsets?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "test-aerospike/auth",
"images": ["aerospike/aerospike-server:4.5.0.5"],
"metadata": {},
"spec": {},
"status": {}
}
],
"metadata": {
"recordCount": 4
}
}
GET /services/:service_code/:environment_name/statefulsets?cluster_id=:cluster_id
Retrieve a list of all stateful sets in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the stateful sets. |
| Attributes | |
|---|---|
id string |
The id of the stateful set |
metadata object |
The metadata of the stateful set |
specobject |
The specification used to create and run the stateful set |
statusobject |
The status information of the stateful set |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a stateful set
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/statefulsets/test-aerospike/auth?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "test-aerospike/auth",
"replicaRatio": "1 / 1",
"images": ["aerospike/aerospike-server:4.5.0.5"],
"apiVersion": "apps/v1",
"kind": "StatefulSet",
"metadata": {},
"spec": {},
"status": {}
}
}
GET /services/:service_code/:environment_name/statefulsets/:id?cluster_id=:cluster_id
Retrieve a stateful set and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the stateful set. |
| Attributes | |
|---|---|
id string |
The id of the stateful set |
metadata object |
The metadata of the stateful set |
specobject |
The specification used to create and run the stateful set |
statusobject |
The status information of the stateful set |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a stateful set
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/statefulsets?cluster_id=a_cluster_id"
Content-Type: application/json
{
"apiVersion": "apps/v1",
"kind":"StatefulSet",
"metadata": {
"name": "stateful-set-name",
"namespace": "default"
},
"spec": {
"selector": {
"matchLabels": {
"app": "nginx"
}
},
"template": {
"metadata": {
"labels": {
"app": "nginx"
}
},
"spec": {
"containers": [
{
"name": "nginx",
"image": "k8s.gcr.io/nginx-slim:0.8"
}
]
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/statefulsets?cluster_id=:cluster_id
Create a stateful set in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the stateful set |
metadata object |
The metadata of the stateful set |
metadata.name string |
The name of the stateful set |
specobject |
The specification used to create and run the stateful set |
spec.selectorobject |
The label query over the stateful set's resources |
spec.templateobject |
The data a stateful set's pod should have when created |
spec.specobject |
The specification used to create and run the pod(s) within the stateful set |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the stateful set is created |
spec.selector.matchLabelsobject |
The key value pairs retrieved by a label query from a stateful set |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create stateful set task. |
taskStatus string |
The status of the operation. |
Replace a stateful set
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/statefulsets/stateful-set-name/default"
Content-Type: application/json
{
"apiVersion": "apps/v1",
"kind": "StatefulSet",
"metadata": {
"name": "stateful-set-name",
"namespace": "default"
},
"spec": {
"selector": {
"matchLabels": {
"app": "nginx"
}
},
"template": {
"metadata": {
"labels": {
"app": "nginx"
}
},
"spec": {
"containers": [
{
"name": "nginx",
"image": "k8s.gcr.io/nginx-slim:0.8"
}
]
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/statefulsets/:id
Replace a stateful set in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the stateful set. |
metadata object |
The metadata of the stateful set. |
metadata.name string |
The name of the stateful set. |
specobject |
The specification used to replaced and run the stateful set. |
spec.selectorobject |
The label query over the stateful set's of resources. |
spec.templateobject |
The data a stateful set's pod should have when replaced. |
spec.specobject |
The specification used to replace and run the pod(s) within the stateful set. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the stateful set is replaced. |
spec.selector.matchLabelsobject |
The key value pairs retrieved by a label query from a stateful set. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace stateful set task. |
taskStatus string |
The status of the operation. |
Delete a stateful set
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/statefulsets/my-aerospike/default"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/statefulsets/:id?cluster_id=:cluster_id
Delete a stateful set from a given environment.
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete stateful set task. |
taskStatus string |
The status of the operation. |
Networking (k8s)
Services
List services
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/services?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "alaintest-aerospike/default",
"ports": ["3000/TCP", "3002/TCP"],
"type": "ClusterIP",
"metadata": {},
"spec": {},
"status": {
"loadBalancer": {}
}
},
{
"id": "alertmanager-operated/monitoring",
"ports": ["9093/TCP", "9094/TCP", "9094/UDP"],
"type": "NodePort",
"apiVersion": "v1",
"kind": "Service",
"metadata": {},
"spec": {},
"status": {
"loadBalancer": {}
}
}
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/services?cluster_id=:cluster_id
Retrieve a list of all services in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the service. |
| Attributes | |
|---|---|
id string |
The id of the service |
metadata object |
The metadata of the service |
metadata.name string |
The name of the service |
metadata.namespace string |
The namespace in which the service is created |
metadata.uid object |
The UUID of the service |
type object |
The container images within a service |
portsobject |
The list of ports that are exposed by this service |
specobject |
The attributes that a user creates on a service |
spec.selectorobject |
The keys and values corresponding to pod labels, used to determine where service traffic will be routed |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a service
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/services/test-aerospike/auth?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "test-aerospike/auth",
"ports": ["3000/TCP", "3002/TCP"],
"type": "ClusterIP",
"apiVersion": "v1",
"kind": "Service",
"metadata": {},
"spec": {},
"status": {
"loadBalancer": {}
}
}
}
GET /services/:service_code/:environment_name/services/:id?cluster_id=:cluster_id
Retrieve a service and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the service. |
| Attributes | |
|---|---|
id string |
The id of the service |
metadata object |
The metadata of the service |
metadata.name string |
The name of the service |
metadata.namespace string |
The namespace in which the service is created |
metadata.uid object |
The UUID of the service |
type object |
The container images within a service |
portsobject |
The list of ports that are exposed by this service |
specobject |
The attributes that a user creates on a service |
spec.selectorobject |
The keys and values corresponding to pod labels, used to determine where service traffic will be routed |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a service
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/services"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Service",
"metadata": {
"name": "service-name",
"namespace": "default"
},
"spec": {
"ports": [
{
"port": 3000,
"protocol": "TCP"
}
],
"type": "ClusterIP"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/services/:id?cluster_id=:cluster_id
Create a service in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the service. |
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the service. |
metadata object |
The metadata of the service. |
metadata.name string |
The name of the service. |
specobject |
The specification used to create and run the service. |
spec.selectorobject |
The label query over the service's set of resources. |
spec.portsobject |
The list of ports that are exposed by this service. |
spec.typeobject |
The type of service (ClusterIP, NodePort, ExternalName or LoadBalancer) |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the service is created. |
spec.selector.matchLabelsobject |
The key value pairs retrieved by a label query from a service. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create service task. |
taskStatus string |
The status of the operation. |
Replace a service
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/services/service-name/default?cluster_id=test-cluster"
Request body example:
{
"type": "LoadBalancer",
"ports": [
"4000/TCP"
],
"apiVersion": "v1",
"kind": "Service",
"metadata": {
"creationTimestamp": "2020-08-13T11:05:00.000-04:00",
"name": "service-name",
"namespace": "default",
"resourceVersion": "170742452",
"selfLink": "/api/v2/namespaces/default/services/service-name",
"uid": "a84c8fea-f9d9-47ab-8e58-37059e9f18bd"
},
"spec": {
"clusterIP": "10.245.44.45",
"externalTrafficPolicy": "Cluster",
"ports": [
{
"nodePort": 31167,
"port": 3000,
"protocol": "TCP",
"targetPort": 306
}
],
"sessionAffinity": "ClientIP",
"sessionAffinityConfig": {
"clientIP": {
"timeoutSeconds": 10555
}
},
"type": "LoadBalancer"
},
"status": {
"loadBalancer": {}
}
}
PUT /services/:service_code/:environment_name/services/:id?cluster_id=:cluster_id
Replace a service in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the service. |
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the service. |
metadata object |
The metadata of the service. |
metadata.name string |
The name of the service. |
specobject |
The specification used to create and run the service. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace service task. |
taskStatus string |
The status of the operation. |
Delete a service
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/services/test-service/default?cluster_id=test-cluster"
DELETE /services/:service_code/:environment_name/services/:id?cluster_id=:cluster_id
Delete a service from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the service. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete service task. |
taskStatus string |
The status of the operation. |
Ingresses V1Beta1
Ingress v1beta1 has been deprecated in this API as of 26.7.0 following the removal of support by kubernetes. Please use the ingress v1 api instead.
Ingresses V1
List ingresses V1
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/ingressesv1?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "cloudmc/cmc-stg",
"endpoint": "http://cmc.cloudmc-staging-endpoint.com",
"service": {
"port": "8080",
"name": "cloudmc"
},
"metadata": {
"annotations": {},
"creationTimestamp": "2019-07-11T10:00:18.000-04:00",
"generation": 10,
"name": "cloudmc",
"namespace": "cmc-stg",
"resourceVersion": "143213903",
"uid": "376bc4c5-a3e4-11e9-b6bd-02006e76001e"
},
"spec": {
"rules": [],
"tls": []
},
"status": {
"loadBalancer": {}
}
},
{
"id": "cm-acme-http-solver-75png/auth",
"endpoint": "http://cmc.cloudmc-staging-endpoint.com",
"service": {
"port": "8089",
"name": "cm-acme-http-solver-2x5gv"
},
"metadata": {
"annotations": {},
"creationTimestamp": "2020-06-24T11:00:49.000-04:00",
"generateName": "cm-acme-http-solver-",
"generation": 1,
"labels": {
"acme.cert-manager.io/http-domain": "1965164889",
"acme.cert-manager.io/http-token": "820448657",
"acme.cert-manager.io/http01-solver": "true"
},
"name": "cm-acme-http-solver-75png",
"namespace": "auth",
"ownerReferences": [],
"resourceVersion": "143213968",
"uid": "48720f48-f2bc-45fc-95c5-60cae8ffe11e"
},
"spec": {
"rules": []
},
"status": {
"loadBalancer": {}
}
}
]
}
GET /services/:service_code/:environment_name/ingressesv1?cluster_id=:cluster_id
Retrieve a list of all ingresses V1 in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the ingress. |
| Attributes | |
|---|---|
id string |
The id of the ingress |
endpoint string |
The endpoint of the ingress |
service object |
The service associated with the ingress |
service.port string |
The port of the service associated with the ingress |
service.name string |
The name of the service associated with the ingress |
metadata object |
The metadata of the ingress |
metadata.name string |
The name of the ingress |
metadata.namespace string |
The namespace in which the ingress is created |
metadata.labels object |
The labels associated with the ingress |
metadata.uid object |
The UUID of the ingress |
specobject |
The attributes that a user specifies for an ingress |
Note that the list is not complete, since it is referring to the kubernetes api details.
Get an ingress V1
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/ingressesv1/cloudmc/cmc-stg?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "cloudmc/cmc-stg",
"endpoint": "http://cmc.cloudmc-staging-endpoint.com",
"service": {
"port": "8080",
"name": "cloudmc"
},
"metadata": {
"annotations": {},
"creationTimestamp": "2019-07-11T10:00:18.000-04:00",
"generation": 10,
"name": "cloudmc",
"namespace": "cmc-stg",
"resourceVersion": "143213903",
"uid": "376bc4c5-a3e4-11e9-b6bd-02006e76001e"
},
"spec": {
"rules": [],
"tls": []
},
"status": {
"loadBalancer": {}
}
}
}
GET /services/:service_code/:environment_name/ingressesv1/:id?cluster_id=:cluster_id
Retrieve an ingress V1 and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the ingress. |
| Attributes | |
|---|---|
id string |
The id of the ingress |
endpoint string |
The endpoint of the ingress |
service object |
The service associated with the ingress |
service.port string |
The port of the service associated with the ingress |
service.name string |
The name of the service associated with the ingress |
metadata object |
The metadata of the ingress |
metadata.name string |
The name of the ingress |
metadata.namespace string |
The namespace in which the ingress is created |
metadata.labels object |
The labels associated with the ingress |
metadata.uid object |
The UUID of the ingress |
specobject |
The attributes that a user specifies for an ingress |
Note that the list is not complete, since it is referring to the kubernetes api details.
Create an ingress V1
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/ingressesv1"
Content-Type: application/json
{
"apiVersion": "networking.k8s.io/v1",
"kind": "Ingress",
"metadata": {
"name": "ingress-name",
"namespace": "default",
"annotations": {
"nginx.ingress.kubernetes.io/rewrite-target": "/"
}
},
"spec": {
"rules": [
{
"hostname": "endpoint.com",
"http": {
"paths": [
{
"path": "/testpath",
"pathType": "Prefix",
"backend": {
"service": {
"name": "test",
"port": {
"number": 80
}
}
}
}
]
}
}
]
}
}
POST /services/:service_code/:environment_name/ingressesv1/:id?cluster_id=:cluster_id
Create an ingress V1 in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the ingress. |
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the ingress. |
metadata object |
The metadata of the ingress. |
metadata.name string |
The name of the ingress. |
specobject |
The specification used to create and run the ingress. |
spec.rulesobject |
The list of host rules used to configure the ingress. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the ingress is created. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create ingress task. |
taskStatus string |
The status of the operation. |
Replace an ingress V1
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/ingressesv1/ingress-name/default?cluster_id=test-cluster"
Request body example:
{
"endpoint": "http://my-endpoint.com",
"service": {
"port": "6556",
"name": "test"
},
"apiVersion": "networking.k8s.io/v1",
"kind": "Ingress",
"metadata": {
"creationTimestamp": "2020-08-13T14:13:42.000-04:00",
"generation": 3,
"name": "ingress-name",
"namespace": "default",
"resourceVersion": "170302224",
"uid": "c67e6a6a-2b07-4976-8b3d-2ec9fd91ae5d"
},
"spec": {
"rules": [
{
"host": "my-endpoint.com",
"http": {
"paths": [
{
"backend": {
"service": {
"name": "test",
"port": {
"number": 6556
}
}
},
"path": "/testpath"
}
]
}
}
]
},
"status": {
"loadBalancer": {
"ingress": [
{
"hostname": "hostname-worker-01"
},
{
"hostname": "hostname-worker-02"
},
{
"hostname": "hostname-worker-03"
},
{
"hostname": "hostname-worker-04"
}
]
}
}
}
PUT /services/:service_code/:environment_name/ingressesv1/:id?cluster_id=:cluster_id
Replace an ingress V1 in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the ingress. |
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the ingress. |
metadata object |
The metadata of the ingress. |
metadata.name string |
The name of the ingress. |
specobject |
The specification used to create and run the ingress. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace ingress task. |
taskStatus string |
The status of the operation. |
Delete an ingress V1
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/ingressesv1/test-ingress/default?cluster_id=test-cluster"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/ingressesv1/:id?cluster_id=:cluster_id
Delete an ingress V1 from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the ingress. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete ingress task. |
taskStatus string |
The status of the operation. |
Configuration
Config Maps
List config maps
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/configmaps?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "coredns/kube-system",
"data": {
"Corefile": ".:53 {\n errors\n health\n kubernetes cluster.local in-addr.arpa ip6.arpa {\n pods insecure\n upstream\n fallthrough in-addr.arpa ip6.arpa\n }\n prometheus :9153\n forward . /etc/resolv.conf\n cache 30\n loop\n reload\n loadbalance\n import custom/.override\n}\nimport custom/.server\n"
},
"metadata": {}
}
],
"metadata": {
"recordCount": 4
}
}
GET /services/:service_code/:environment_name/configmaps?cluster_id=:cluster_id
Retrieve a list of all config maps in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the config maps. |
| Attributes | |
|---|---|
id string |
The id of the config map. |
apiVersion string |
The API version used to retrieve this config map. |
metadata object |
The metadata of the config map. |
Get a config map
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/configmaps/coredns/kube-system?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "coredns/kube-system",
"apiVersion": "v1",
"data": {
"Corefile": ".:53 {\n errors\n health\n kubernetes cluster.local in-addr.arpa ip6.arpa {\n pods insecure\n upstream\n fallthrough in-addr.arpa ip6.arpa\n }\n prometheus :9153\n forward . /etc/resolv.conf\n cache 30\n loop\n reload\n loadbalance\n import custom/.override\n}\nimport custom/.server\n"
},
"kind": "ConfigMap",
"metadata": {}
}
}
GET /services/:service_code/:environment_name/configmaps/:id?cluster_id=:cluster_id
Retrieve a config map and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the config map. |
| Attributes | |
|---|---|
id string |
The id of the config map. |
apiVersion string |
The API version used to retrieve this config map. |
metadata object |
The metadata of the config map. |
Create a config map
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/configmaps?cluster_id=:cluster_id"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "ConfigMap",
"metadata": {
"name": "game-demo"
},
"data": {
"player_initial_lives": "3",
"ui_properties_file_name": "user-interface.properties",
"game.properties": "enemy.types=aliens,monsters\nplayer.maximum-lives=5\n",
"user-interface.properties": "color.good=purple\ncolor.bad=yellow\nallow.textmode=true\n"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/configmaps?cluster_id=:cluster_id
Create a config map in a given environment.
| Required Attributes | |
|---|---|
cluster_id string |
The id of the cluster in which to create the config map. |
apiVersion string |
The api version (versioned schema) of the config map. |
metadata object |
The metadata of the config map. |
metadata.name string |
The name of the config map. |
dataobject |
The non-confidential data (in key-value pairs) stored in the config map. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the config map is created |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create config maps task. |
taskStatus string |
The status of the operation. |
Replace a config map
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/configmaps/game-demo/default?cluster_id=:cluster_id"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "ConfigMap",
"metadata": {
"name": "game-demo",
"namespace": "default"
},
"data": {
"player_initial_lives": "5",
"ui_properties_file_name": "user-interface.properties",
"game.properties": "enemy.types=aliens,monsters\nplayer.maximum-lives=5\n",
"user-interface.properties": "color.good=purple\ncolor.bad=yellow\nallow.textmode=true\n"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/configmaps/:id?cluster_id=:cluster_id
Replace a config map in a given environment.
| Required Attributes | |
|---|---|
cluster_id string |
The id of the cluster in which to replace the config map. |
apiVersion string |
The api version (versioned schema) of the config map. |
metadata object |
The metadata of the config map. |
metadata.name string |
The name of the config map. |
dataobject |
The non-confidential data (in key-value pairs) stored in the config map. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the config map is replaced. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace config maps task. |
taskStatus string |
The status of the operation. |
Delete a config map
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/configmaps/cert-manager-cainjector-leader-election/kube-system?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/configmaps/:id?cluster_id=:cluster_id
Delete a config map from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to delete the config map. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete config map task. |
taskStatus string |
The status of the operation. |
Secrets
List secrets
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/secrets?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "default-token-xxxmt/default",
"apiVersion": "v1",
"encodedData": {
"ca.crt": "LS0tLS...",
"namespace": "a3ViZS1zeXN0ZW0=",
"token": "ZXlKa..."
},
"kind": "Secret",
"metadata": {},
"type": "kubernetes.io/service-account-token"
}
],
"metadata": {
"recordCount": 100
}
}
GET /services/:service_code/:environment_name/secrets?cluster_id=:cluster_id
Retrieve a list of all secrets in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the secrets. |
| Attributes | |
|---|---|
id string |
The id of the secret. |
apiVersion string |
The API version used to retrieve the secret. |
encodedDataobject |
The base64 encoded data stored in the secret. |
metadata object |
The metadata of the secret. |
type string |
A string used to facilitate programmatic handling of a secret's data. |
Get a secret
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/secrets/default-token-xxxmt/default?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "default-token-xxxmt/default",
"apiVersion": "v1",
"encodedData": {
"ca.crt": "LS0tLS...",
"namespace": "a3ViZS1zeXN0ZW0=",
"token": "ZXlKa..."
},
"kind": "Secret",
"metadata": {},
"type": "kubernetes.io/service-account-token"
}
}
GET /services/:service_code/:environment_name/secrets/:id?cluster_id=:cluster_id
Retrieve a secret and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the secret. |
| Attributes | |
|---|---|
id string |
The id of the secret. |
apiVersion string |
The API version used to retrieve the secret. |
encodedDataobject |
The base64 encoded data stored in the secret. |
metadata object |
The metadata of the secret. |
type string |
A string used to facilitate programmatic handling of a secret's data. |
Create a secret
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/secrets"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Secret",
"metadata": {
"name": "mysecret"
},
"type": "Opaque",
"stringData": {
"username": "my-username",
"password": "my-password"
}
}
# OR
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/secrets?cluster_id=:cluster_id"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Secret",
"metadata": {
"name": "mysecret"
},
"type": "Opaque",
"encodedData": {
"username": "YWRtaW4=",
"password": "MWYyZDFlMmU2N2Rm"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/secrets?cluster_id=:cluster_id
Create a secret in a given environment.
| Required Attributes | |
|---|---|
cluster_id string |
The id of the cluster in which to create the secret. |
apiVersion string |
The api version (versioned schema) of the secret. |
metadata object |
The metadata of the secret. |
metadata.name string |
The name of the secret. |
One of the following two attributes is also required.
| Attributes | |
|---|---|
encodedDataobject |
The base64 encoded data stored in the secret. |
stringDataobject |
The non-base64 encoded data to be encoded when the secret is created. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the secret is created |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create secret task. |
taskStatus string |
The status of the operation. |
Replace a secret
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/secrets/my-secret/shhh"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Secret",
"metadata": {
"name": "mysecret"
},
"type": "Opaque",
"stringData": {
"username": "my-username",
"password": "my-new-password"
}
}
# OR
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/secrets?cluster_id=:cluster_id"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Secret",
"metadata": {
"name": "mysecret",
"namespace": "shhh"
},
"type": "Opaque",
"encodedData": {
"username": "YWRtaW4=",
"password": "MWYyFZDlMmU2N2Rm"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/secrets/:id?cluster_id=:cluster_id
Replace a secret in a given environment.
| Required Attributes | |
|---|---|
cluster_id string |
The id of the cluster in which to replace the secret. |
apiVersion string |
The api version (versioned schema) of the secret. |
metadata object |
The metadata of the secret. |
metadata.name string |
The name of the secret. |
One of the following two attributes is also required.
| Attributes | |
|---|---|
encodedDataobject |
The base64 encoded data stored in the secret. |
stringDataobject |
The non-base64 encoded data to be encoded when the secret is replaced. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the secret is replaced |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace secret task. |
taskStatus string |
The status of the operation. |
Delete a secret
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/secrets/default-token-xxxmt/default?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/secrets/:id?cluster_id=:cluster_id
Delete a secret from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to delete the secret. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete secret task. |
taskStatus string |
The status of the operation. |
Storage (k8s)
Storage Classes
List storage classes
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/storageclasses?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "rook-ceph-block",
"isDefault": true,
"allowVolumeExpansion": true,
"metadata": {
"annotations": {
"storageclass.kubernetes.io/is-default-class": "true"
},
"creationTimestamp": "2020-04-20T16:08:54.000-04:00",
"name": "rook-ceph-block",
"resourceVersion": "107033002",
"selfLink": "/apis/storage.k8s.io/v1/storageclasses/rook-ceph-block",
"uid": "f289c0e6-3f20-4274-8cb8-5db8b34dece6"
},
"parameters": {
"clusterID": "rook-ceph",
"csi.storage.k8s.io/controller-expand-secret-name": "rook-csi-rbd-provisioner",
"csi.storage.k8s.io/controller-expand-secret-namespace": "rook-ceph",
"csi.storage.k8s.io/fstype": "ext4",
"csi.storage.k8s.io/node-stage-secret-name": "rook-csi-rbd-node",
"csi.storage.k8s.io/node-stage-secret-namespace": "rook-ceph",
"csi.storage.k8s.io/provisioner-secret-name": "rook-csi-rbd-provisioner",
"csi.storage.k8s.io/provisioner-secret-namespace": "rook-ceph",
"imageFeatures": "layering",
"imageFormat": "2",
"pool": "replicapool"
},
"provisioner": "rook-ceph.rbd.csi.ceph.com",
"reclaimPolicy": "Delete",
"volumeBindingMode": "Immediate"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/storageclasses?cluster_id=:cluster_id
Retrieve a list of all storage classes in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the storage classes. |
| Attributes | |
|---|---|
id string |
The id of the storage class. This is the name of the resource. |
isDefault boolean |
Whether or not the storage class is the default one. |
allowVolumeExpansion boolean |
Whether not the storage class allows for expandable volumes. |
metadata object |
The metadata of the storage class. |
parameters object |
The parameters for the storage provisioner. These are storage provisioner specific and you will likely have to read external documentation. |
provisioner string |
The provisioner for the storage class. |
reclaimPolicy string |
The default volume reclaim policy for this storage class. You have a choice between Reclaim or Delete. |
volumeBindingMode string |
The default volume binding model for this storage class. You have a choice between Immediate or WaitForFirstConsumer. |
Get a storage class
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/storageclasses/rook-ceph-block?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "rook-ceph-block",
"isDefault": true,
"allowVolumeExpansion": true,
"metadata": {
"annotations": {
"storageclass.kubernetes.io/is-default-class": "true"
},
"creationTimestamp": "2020-04-20T16:08:54.000-04:00",
"name": "rook-ceph-block",
"resourceVersion": "107033002",
"selfLink": "/apis/storage.k8s.io/v1/storageclasses/rook-ceph-block",
"uid": "f289c0e6-3f20-4274-8cb8-5db8b34dece6"
},
"parameters": {
"clusterID": "rook-ceph",
"csi.storage.k8s.io/controller-expand-secret-name": "rook-csi-rbd-provisioner",
"csi.storage.k8s.io/controller-expand-secret-namespace": "rook-ceph",
"csi.storage.k8s.io/fstype": "ext4",
"csi.storage.k8s.io/node-stage-secret-name": "rook-csi-rbd-node",
"csi.storage.k8s.io/node-stage-secret-namespace": "rook-ceph",
"csi.storage.k8s.io/provisioner-secret-name": "rook-csi-rbd-provisioner",
"csi.storage.k8s.io/provisioner-secret-namespace": "rook-ceph",
"imageFeatures": "layering",
"imageFormat": "2",
"pool": "replicapool"
},
"provisioner": "rook-ceph.rbd.csi.ceph.com",
"reclaimPolicy": "Delete",
"volumeBindingMode": "Immediate"
}
}
GET /services/:service_code/:environment_name/storageclasses/:id?cluster_id=:cluster_id
Retrieve a storage class and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the storage classes. |
| Attributes | |
|---|---|
id string |
The id of the storage class. This is the name of the resource |
isDefault boolean |
Whether or not the storage class is the default one |
allowVolumeExpansion boolean |
Whether not the storage class allows for expandable volumes. |
metadata object |
The metadata of the storage class. |
parameters object |
The parameters for the storage provisioner. These are storage provisioner specific and you will likely have to read external documentation. |
provisioner string |
The provisioner for the storage class |
reclaimPolicy string |
The default volume reclaim policy for this storage class. You have a choice between Reclaim or Delete. |
volumeBindingMode string |
The default volume binding model for this storage class. You have a choice between Immediate or WaitForFirstConsumer. |
Create a storage class
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/storageclasses?cluster_id=a_cluster_id"
Content-Type: application/json
{
"apiVersion": "storage.k8s.io/v1",
"kind": "StorageClass",
"metadata": {
"name": "local-storage-name"
},
"provisioner": "kubernetes.io/no-provisioner",
"volumeBindingMode": "WaitForFirstConsumer"
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/storageclasses?cluster_id=:cluster_id
Create a storage class in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the storage class. |
metadata object |
The metadata of the storage class. |
metadata.name string |
The name of the storage class. |
provisioner string |
The provisioner for the storage class |
volumeBindingMode string |
The default volume binding model for this storage class. You have a choice between Immediate or WaitForFirstConsumer. |
| Optional Attributes | |
|---|---|
reclaimPolicy string |
The default volume reclaim policy for this storage class. You have a choice between Reclaim or Delete. |
parameters object |
The parameters for the storage provisioner. These are storage provisioner specific and you will likely have to read external documentation. |
allowVolumeExpansion boolean |
Whether not the storage class allows for expandable volumes. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create stateful set task. |
taskStatus string |
The status of the operation. |
Replace a storage class
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/storageclasses/rook-ceph-block?cluster_id=a_cluster_id"
Content-Type: application/json
{
"apiVersion": "storage.k8s.io/v1",
"metadata": {
"name": "hostpath"
},
"provisioner": "docker.io/hostpath"
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/storageclasses/:id?cluster_id=:cluster_id
Replace a storage class in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the storage class. |
metadata object |
The metadata of the storage class. |
metadata.name string |
The name of the storage class. |
provisionerobject |
The type of provisioner. |
| Optional Attributes | |
|---|---|
reclaimPolicy string |
Dynamically provisioned PersistentVolumes of this storage class are created with this reclaimPolicy. Defaults to Delete. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace storage class task. |
taskStatus string |
The status of the operation. |
Delete a storage class
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/storageclasses/rook-ceph-block?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/storageclasses/:id?cluster_id=:cluster_id
Delete a storage class from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the storage class. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete storage class task. |
taskStatus string |
The status of the operation. |
Persistent volumes
List persistent volumes
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumes?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "pvc-05097a93-120d-45d2-aaab-0f273849fccd",
"metadata": {
"annotations": {
"pv.kubernetes.io/provisioned-by": "rook-ceph.rbd.csi.ceph.com"
},
"creationTimestamp": "2020-07-03T09:12:17.000-04:00",
"finalizers": ["kubernetes.io/pv-protection"],
"name": "pvc-05097a93-120d-45d2-aaab-0f273849fccd",
"resourceVersion": "147569183",
"selfLink": "/api/v2/persistentvolumes/pvc-05097a93-120d-45d2-aaab-0f273849fccd",
"uid": "2e20a8fb-d90c-4c39-acd8-7007f85e2d8e"
},
"spec": {
"accessModes": ["ReadWriteOnce"],
"capacity": {
"storage": "8Gi"
},
"claimRef": {
"apiVersion": "v1",
"kind": "PersistentVolumeClaim",
"name": "data-cmc-cluster-zookeeper-1",
"namespace": "cmc-kafka",
"resourceVersion": "147569124",
"uid": "05097a93-120d-45d2-aaab-0f273849fccd"
},
"csi": {
"driver": "rook-ceph.rbd.csi.ceph.com",
"fsType": "ext4",
"nodeStageSecretRef": {
"name": "rook-csi-rbd-node",
"namespace": "rook-ceph"
},
"volumeAttributes": {
"clusterID": "rook-ceph",
"imageFeatures": "layering",
"imageFormat": "2",
"pool": "replicapool",
"storage.kubernetes.io/csiProvisionerIdentity": "1593101040137-8081-rook-ceph.rbd.csi.ceph.com"
},
"volumeHandle": "0001-0009-rook-ceph-0000000000000001-d11d2a4d-bd2e-11ea-b56e-7a7db811cab1"
},
"persistentVolumeReclaimPolicy": "Delete",
"storageClassName": "rook-ceph-block",
"volumeMode": "Filesystem"
},
"status": {
"phase": "Bound"
}
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/persistentvolumes?cluster_id=:cluster_id
Retrieve a list of all persistent volumes in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the persistent volumes. |
| Attributes | |
|---|---|
id string |
The id of the persistent volume. This is the name of the resource. |
metadata object |
The metadata of the persistent volume. |
spec object |
The specification of the persistent volume. |
spec.accessModes string |
The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes). |
spec.capacity.storage string |
Storage capacity of the persistent volume. |
spec.persistentVolumeReclaimPolicy string |
One of Retain (manual reclamation), Recycle (basic scrub) or Delete (associated storage asset such as AWS EBS, GCE PD, Azure Disk, or OpenStack Cinder volume is deleted). |
spec.storageClassName string |
Storage class associated to the volume. |
spec.capacity.volumeMode string |
If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device. |
status.phase string |
Volume is in one of the following phases: Available, Bound, Released or Failed. |
Get a persistent volume
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumes/pvc-05097a93-120d-45d2?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"id": "pvc-05097a93-120d-45d2",
"metadata": {
"annotations": {
"pv.kubernetes.io/provisioned-by": "rook-ceph.rbd.csi.ceph.com"
},
"creationTimestamp": "2020-07-03T09:12:17.000-04:00",
"finalizers": ["kubernetes.io/pv-protection"],
"name": "pvc-05097a93-120d-45d2-aaab-0f273849fccd",
"resourceVersion": "147569183",
"selfLink": "/api/v2/persistentvolumes/pvc-05097a93-120d-45d2-aaab-0f273849fccd",
"uid": "2e20a8fb-d90c-4c39-acd8-7007f85e2d8e"
},
"spec": {
"accessModes": ["ReadWriteOnce"],
"capacity": {
"storage": "8Gi"
},
"claimRef": {
"apiVersion": "v1",
"kind": "PersistentVolumeClaim",
"name": "data-cmc-cluster-zookeeper-1",
"namespace": "cmc-kafka",
"resourceVersion": "147569124",
"uid": "05097a93-120d-45d2-aaab-0f273849fccd"
},
"csi": {
"driver": "rook-ceph.rbd.csi.ceph.com",
"fsType": "ext4",
"nodeStageSecretRef": {
"name": "rook-csi-rbd-node",
"namespace": "rook-ceph"
},
"volumeAttributes": {
"clusterID": "rook-ceph",
"imageFeatures": "layering",
"imageFormat": "2",
"pool": "replicapool",
"storage.kubernetes.io/csiProvisionerIdentity": "1593101040137-8081-rook-ceph.rbd.csi.ceph.com"
},
"volumeHandle": "0001-0009-rook-ceph-0000000000000001-d11d2a4d-bd2e-11ea-b56e-7a7db811cab1"
},
"persistentVolumeReclaimPolicy": "Delete",
"storageClassName": "rook-ceph-block",
"volumeMode": "Filesystem"
},
"status": {
"phase": "Bound"
}
}
GET /services/:service_code/:environment_name/persistentvolumes/:id?cluster_id=:cluster_id
Retrieve a persistent volume and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the persistent volume. |
| Attributes | |
|---|---|
id string |
The id of the persistent volume. This is the name of the resource. |
metadata object |
The metadata of the persistent volume. |
spec object |
The specification of the persistent volume. |
spec.accessModes string |
The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes). |
spec.capacity.storage string |
Storage capacity of the persistent volume. |
spec.persistentVolumeReclaimPolicy string |
One of Retain (manual reclamation), Recycle (basic scrub) or Delete (associated storage asset such as AWS EBS, GCE PD, Azure Disk, or OpenStack Cinder volume is deleted). |
spec.storageClassName string |
Storage class associated to the volume. |
spec.capacity.volumeMode string |
If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device. |
status.phase string |
Volume is in one of the following phases: Available, Bound, Released or Failed. |
Create a persistent volume
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumes"
Content-Type: application/json
{
"apiVersion": "v1",
"metadata": {
"name": "small-pvc",
"namespace": "default"
},
"spec": {
"accessModes": [
"ReadWriteOnce"
],
"resources": {
"requests": {
"storage": "10G"
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/persistentvolumes
Create a persistent volume in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the persistent volume. |
metadata object |
The metadata of the persistent volume. |
metadata.name string |
The name of the persistent volume. |
spec object |
The spec for the persistent volume. |
spec.accessModes array |
A list of access modes, the options are: ReadWriteOnce, ReadOnlyMany and ReadWriteMany. |
spec.capacity.storage string |
Measured in bytes. You can express storage as a plain integer or as a fixed-point integer using one of these suffixes: E, P, T, G, M, K. You can also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki. |
spec.<VOLUME_TYPE> object |
Volume types are identified by name and what volume types are supported differ heavily by Kubernetes deployment. The contents of the object also depend on the volume type. Examples of common volumes types are nfs, hostPath, or local. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the pod is created, if not specified will create the persistent volume in default. |
spec.storageClassName string |
Storage class associated to the volume. |
spec.claimRef array |
The name of the PersistentVolumeClaim associated to the persistent volume. |
spec.mountOptions array |
Mount options for when a Persistent Volume is mounted on a node. |
spec.nodeAffinity array |
Defines constraints that limit what nodes this volume can be accessed from. |
spec.persistentVolumeReclaimPolicy array |
One of Retain (manual reclamation), Recycle (basic scrub) or Delete (associated storage asset such as AWS EBS, GCE PD, Azure Disk, or OpenStack Cinder volume is deleted). |
spec.volumeMode array |
If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device. |
status.phase string |
Volume is in one of the following phases: Available, Bound, Released or Failed. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create persistent volume task. |
taskStatus string |
The status of the operation. |
Replace a persistent volume
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumes/my-persistent-volume?cluster_id=a_cluster_id"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "PersistentVolume",
"metadata": {
"annotations": {
"key": "value"
},
"name": "persistentvolumes-name"
},
"spec": {
"accessModes": [
"ReadWriteMany"
],
"capacity": {
"storage": "2Gi"
},
"claimRef": {
"apiVersion": "v1",
"kind": "PersistentVolumeClaim",
"name": "pv-claim-name",
"namespace": "default",
"resourceVersion": "259087",
"uid": "11957feb-1acc-4c7e-911e-f77d5d7be5ac"
},
"hostPath": {
"path": "/etc/path"
},
"persistentVolumeReclaimPolicy": "Retain",
"storageClassName": "standard",
"volumeMode": "Filesystem"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/persistentvolumes/:id?cluster_id=a_cluster_id
Replace a persistent volume in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the volume. |
metadata object |
The metadata of the volume. |
metadata.name string |
The name of the volume. |
specobject |
The specification used to replace and run the volume. |
spec.accessModesstring |
The desired access modes the volume should have. |
spec.capacity.storagestring |
The size of the claim. |
spec.hostPath.pathstring |
The path of the directory on the host. |
| Optional Attributes | |
|---|---|
metadata.annotations string |
Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. |
spec.claimRef string |
part of a bi-directional binding between PersistentVolume and PersistentVolumeClaim. Expected to be non-nil when bound. |
spec.persistentVolumeReclaimPolicy string |
What happens to a persistent volume when released from its claim. |
spec.storageClassName string |
Name of StorageClass to which this persistent volume belongs. Empty value means that this volume does not belong to any StorageClass. |
spec.volumeMode string |
Defines if a volume is intended to be used with a formatted filesystem or to remain in raw block state. Value of Filesystem is implied when not included in spec. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace volume task. |
taskStatus string |
The status of the operation. |
Delete a persistent volume
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumes/pvc-05097a93-120d-45d2?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/persistentvolumes/:id?cluster_id=:cluster_id
Delete a perstent volume from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the perstent volume. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete persistent volume task. |
taskStatus string |
The status of the operation. |
Persistent Volume Claims
List persistent volume claims
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumeclaims?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "cmc-staging-mysql/cmc-stg",
"metadata": {
"annotations": {
"pv.kubernetes.io/bind-completed": "yes",
"pv.kubernetes.io/bound-by-controller": "yes",
"volume.beta.kubernetes.io/storage-provisioner": "rook-ceph.rbd.csi.ceph.com"
},
"creationTimestamp": "2020-04-27T12:01:22.000-04:00",
"finalizers": ["kubernetes.io/pvc-protection"],
"labels": {
"app": "cmc-staging-mysql",
"chart": "mysql-0.4.5",
"heritage": "Helm",
"release": "cmc-staging"
},
"name": "cmc-staging-mysql",
"namespace": "cmc-stg",
"resourceVersion": "111495311",
"selfLink": "/api/v2/namespaces/cmc-stg/persistentvolumeclaims/cmc-staging-mysql",
"uid": "ba115a65-e3c5-4e37-8548-e37ec395e79f"
},
"spec": {
"accessModes": ["ReadWriteOnce"],
"resources": {
"requests": {
"storage": "8Gi"
}
},
"storageClassName": "rook-ceph-block",
"volumeMode": "Filesystem",
"volumeName": "pvc-ba115a65-e3c5-4e37-8548-e37ec395e79f"
},
"status": {
"accessModes": ["ReadWriteOnce"],
"capacity": {
"storage": "8Gi"
},
"phase": "Bound"
}
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/persistentvolumeclaims?cluster_id=:cluster_id
Retrieve a list of all persistent volume claims in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the persistent volume claims. |
| Attributes | |
|---|---|
id string |
The id of the persistent volume claim. This is the name and namespace of the resource. |
metadata object |
The metadata of the persistent volume claim. |
spec object |
The specification of the persistent volume claim. |
spec.accessModes string |
The requested access mode. The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes). |
spec.resources.requests.storage string |
The requested storage capacity of the persistent volume. |
spec.storageClassName string |
Storage class associated to the volume. |
spec.capacity.volumeMode string |
If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device. |
status object |
The status of the persistent volume claim. |
status.phase string |
The claim is in one of the following phases: Pending, Bound, Lost or Terminating. |
status.accessModes string |
The allocated access mode. The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes). |
status.capacity.storage string |
The allocated storage capacity. |
Get a persistent volume claim
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumeclaims/cmc-staging-mysql/cmc-stg?cluster_id=:cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "cmc-staging-mysql/cmc-stg",
"apiVersion": "v1",
"kind": "PersistentVolumeClaim",
"metadata": {
"annotations": {
"pv.kubernetes.io/bind-completed": "yes",
"pv.kubernetes.io/bound-by-controller": "yes",
"volume.beta.kubernetes.io/storage-provisioner": "rook-ceph.rbd.csi.ceph.com"
},
"creationTimestamp": "2020-04-27T12:01:22.000-04:00",
"finalizers": ["kubernetes.io/pvc-protection"],
"labels": {
"app": "cmc-staging-mysql",
"chart": "mysql-0.4.5",
"heritage": "Helm",
"release": "cmc-staging"
},
"name": "cmc-staging-mysql",
"namespace": "cmc-stg",
"resourceVersion": "111495311",
"selfLink": "/api/v2/namespaces/cmc-stg/persistentvolumeclaims/cmc-staging-mysql",
"uid": "ba115a65-e3c5-4e37-8548-e37ec395e79f"
},
"spec": {
"accessModes": ["ReadWriteOnce"],
"resources": {
"requests": {
"storage": "8Gi"
}
},
"storageClassName": "rook-ceph-block",
"volumeMode": "Filesystem",
"volumeName": "pvc-ba115a65-e3c5-4e37-8548-e37ec395e79f"
},
"status": {
"accessModes": ["ReadWriteOnce"],
"capacity": {
"storage": "8Gi"
},
"phase": "Bound"
}
}
}
GET /services/:service_code/:environment_name/persistentvolumeclaims/:id?cluster_id=:cluster_id
Retrieve a persistent volume claim and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the persistent volume claim. |
| Attributes | |
|---|---|
id string |
The id of the persistent volume claim. This is the name and namespace of the resource. |
metadata object |
The metadata of the persistent volume claim. |
spec object |
The specification of the persistent volume claim. |
spec.accessModes string |
The requested access mode. The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes). |
spec.resources.requests.storage string |
The requested storage capacity of the persistent volume. |
spec.storageClassName string |
Storage class associated to the volume. |
spec.capacity.volumeMode string |
If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device. |
status object |
The status of the persistent volume claim. |
status.phase string |
The claim is in one of the following phases: Pending, Bound, Lost or Terminating. |
status.accessModes string |
The allocated access mode. The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes). |
status.capacity.storage string |
The allocated storage capacity. |
Create a persistent volume claim
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumeclaims?cluster_id=a_cluster_id"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "PersistentVolumeClaim",
"metadata": {
"name": "small-pvc",
"namespace": "default"
},
"spec": {
"accessModes": [
"ReadWriteOnce"
],
"resources": {
"requests": {
"storage": "10G"
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/persistentvolumeclaims?cluster_id=:cluster_id
Create a persistent volume claim in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the persistent volume claims. |
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the persistent volume claim. |
metadata object |
The metadata of the persistent volume claim. |
metadata.name string |
The name of the persistent volume claim. |
spec object |
The spec for the persistent volume claim. |
spec.accessModes array |
A list of access modes, the options are: ReadWriteOnce, ReadOnlyMany and ReadWriteMany. |
spec.resources.requests.storage string |
Measured in bytes. You can express storage as a plain integer or as a fixed-point integer using one of these suffixes: E, P, T, G, M, K. You can also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the pod is created, if not specified will create the claim in default. |
spec.storageClassName string |
The storage class for the persistent volume claim, will use the default if not specified. |
spec.resources.limits object |
Limits describe the maximum number of storage resources allowed. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create persistent volume claim task. |
taskStatus string |
The status of the operation. |
Replace a persistent volume claim
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumeclaims/my-persistent-volume-claim/default?cluster_id=a_cluster_id"
Content-Type: application/json
{
"id": "pv-claim-name/default",
"apiVersion": "v1",
"kind": "PersistentVolumeClaim",
"metadata": {
"name": "pv-claim-name",
"namespace": "default"
},
"spec": {
"accessModes": [
"ReadWriteOnce"
],
"resources": {
"requests": {
"storage": "1Gi"
}
},
"storageClassName": "standard",
"volumeName": "persistentvolumes-name",
"dataSource": "dataSource"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/persistentvolumeclaims/:id?cluster_id=:cluster_id
Replace a persistent volume claim in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the claim. |
metadata object |
The metadata of the claim. |
metadata.name string |
The name of the claim. |
specobject |
The specification used to replace and run the claim. |
spec.accessModesstring |
The desired access modes the volume should have. |
spec.resources.requests.storagestring |
The size of the claim. |
spec.storageClassNamestring |
The name of the StorageClass required by the claim. |
| Optional Attributes | |
|---|---|
spec.volumeNamestring |
The binding reference to the PersistentVolume backing this claim. Only required if claim is bound. |
spec.volumemode string |
What type of volume is required by the claim. Value of Filesystem is implied when not included in claim spec. |
spec.dataSource string |
This field can be used to specify either: an existing VolumeSnapshot object, an existing PVC or an existing custom resource/object that implements data population. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace persistent volume claim task. |
taskStatus string |
The status of the operation. |
Delete a persistent volume claim
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumeclaims/cmc-staging-mysql/cmc-stg?cluster_id=:cluster_id"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/persistentvolumeclaims/:id?cluster_id=:cluster_id
Delete a perstent volume claim from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the perstent volume claim. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete persistent volume claim task. |
taskStatus string |
The status of the operation. |
Access control
Service accounts
List service accounts
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/serviceaccounts?cluster_id=:cluster_id"
The above command returns a JSON structured like this:
{
"metadata": {
"name": "vpnkit-controller",
"namespace": "kube-system",
"selfLink": "/api/v2/namespaces/kube-system/serviceaccounts/vpnkit-controller",
"uid": "b9afa8a8-3d64-4605-959f-12bb5c6cfba2",
"resourceVersion": "481",
"creationTimestamp": "2020-09-18T14:47:48Z",
"annotations": {
"kubectl.kubernetes.io/last-applied-configuration": "{\"apiVersion\":\"v1\",\"kind\":\"ServiceAccount\",\"metadata\":{\"annotations\":{},\"name\":\"vpnkit-controller\",\"namespace\":\"kube-system\"}}\n"
}
},
"secrets": [
{
"name": "vpnkit-controller-token-hl674"
}
]
}
]
}
GET /services/:service_code/:environment_name/serviceaccounts?cluster_id=:cluster_id
Retrieve a list of all service accounts in a given environment.
| Attributes | |
|---|---|
id string |
The id of the service account. |
metadata.annotations map |
The annotations of the service account. |
metadata object |
The metadata of the service account. |
metadata.creationTimestamp string |
The date of creation of the service account as a string. |
metadata.name string |
The name of the service account. |
metadata.namespace string |
The namespace in which the service account is created. |
metadata.uid object |
The UUID of the service account. |
metadata.secrets List<object> |
The secrets of the service account. |
secretsSize integer |
The number of secrets of the service account. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a service account
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/serviceaccounts/serviceaccount-name/serviceaccount-namespace?cluster_id=:cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "default",
"age": "1w5d",
"secretsSize": 1,
"metadata": {
"creationTimestamp": "2020-09-18T10:46:40.000-04:00",
"name": "default",
"namespace": "default",
"uid": "80a0de4d-a187-44c3-b691-1481220a5817"
},
"secrets": [
{
"name": "default-token-lrth9"
}
]
},
"fieldTransitions": {},
"operations": []
}
GET /services/:service_code/:environment_name/serviceaccounts/:id?cluster_id=:cluster_id
Retrieve a service account and all its info in a given environment.
| Attributes | |
|---|---|
id string |
The id of the service account. |
metadata object |
The metadata of the service account. |
metadata.creationTimestamp string |
The date of creation of the service account as a string. |
metadata.name string |
The name of the service account. |
metadata.namespace string |
The namespace in which the service account is created. |
metadata.uid object |
The UUID of the service account. |
metadata.secrets List<object> |
The secrets of the service account. |
secretsSize integer |
The number of secrets of the service account. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a service account
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/serviceaccounts?cluster_id=:cluster_id"
Content-Type: application/json
{
"apiVersion": "v1",
"metadata": {
"name": "service-account-name",
"namespace": "default"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/serviceaccounts?cluster_id=:cluster_id
Create a service account in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the service account. |
metadata object |
The metadata of the service account. |
metadata.name string |
The name of the service account. |
metadata.namespace string |
The namespace of the service account. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create service account task. |
taskStatus string |
The status of the operation. |
Replace a service account
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/serviceaccounts/service-account-name/namespace-name?cluster_id=:cluster_id"
Content-Type: application/json
{
"metadata": {
"name": "service-account-name",
"namespace": "namespace-name"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/serviceaccounts/:id?cluster_id=:cluster_id
Replace a service account in a given environment.
| Required Attributes | |
|---|---|
metadata object |
The metadata of the service account. |
metadata.name string |
The name of the service account. |
metadata.namespace string |
The namespace of the service account. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create service account task. |
taskStatus string |
The status of the operation. |
Delete a service account
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/serviceaccounts/my-service-account/my-namespace?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/serviceaccounts/:id?cluster_id=:cluster_id
Delete a service account from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to delete the service account. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete service account task. |
taskStatus string |
The status of the operation. |
Roles
List (namespace) Roles
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/roles?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "role-id",
"age": "1w4d",
"metadata": {
"creationTimestamp": "2020-09-18T10:01:26.000-04:00",
"name": "kubeadm:bootstrap-signer-clusterinfo",
"namespace": "kube-public",
"uid": "57ef0321-e44a-43c9-9f2a-e448c3a66a46"
},
"rules": [
{
"apiGroups": [],
"resourceNames": [],
"resources": [],
"verbs": []
}
]
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/roles?cluster_id=:cluster_id
Retrieve a list of all roles in a given environment.
| Attributes | |
|---|---|
id string |
The id of the role. |
metadata object |
The metadata of the role. |
metadata.creationTimestamp string |
The date of creation of the service account as a string. |
metadata.name string |
The name of the role. |
metadata.namespace string |
The namespace in which the role is created. |
metadata.uid object |
The UUID of the role. |
rules array |
The array of rules associated with this role. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a role
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/roles/role-name/role-namespace?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
The above command returns a JSON structured like this:
{
"data": {
"id": "kubeadm:bootstrap-signer-clusterinfo",
"age": "1w4d",
"apiVersion": "rbac.authorization.k8s.io/v1",
"kind": "Role",
"metadata": {
"creationTimestamp": "2020-09-18T10:01:26.000-04:00",
"name": "kubeadm:bootstrap-signer-clusterinfo",
"namespace": "kube-public",
"uid": "57ef0321-e44a-43c9-9f2a-e448c3a66a47"
},
"rules": [
{
"apiGroups": [],
"resourceNames": [],
"resources": [],
"verbs": []
}
]
}
}
GET /services/:service_code/:environment_name/roles/:id?cluster_id=:cluster_id
Retrieve a role and all its info in a given environment.
| Attributes | |
|---|---|
id string |
The id of the role. |
apiVersion string |
The API version used to retrieve this role. |
metadata object |
The metadata of the role. |
rules array |
The array of rules associated with this role. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a role
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/roles?cluster_id=:cluster_id"
Content-Type: application/json
{
"apiVersion": "rbac.authorization.k8s.io/v1",
"kind": "Role",
"namespace": "default",
"name": "test-name",
"metadata": {
"namespace": "default",
"name": "test-name"
},
"rules": [
{
"apiGroups": [
""
],
"resources": [
"resource"
],
"verbs": [
"get",
"watch"
]
}
]
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/roles?cluster_id=:cluster_id
Create a role in a given environment.
| Attributes | |
|---|---|
id string |
The id of the role. |
apiVersion string |
The API version used to create this role. |
metadata.name string |
The name of the role. |
metadata.namespace string |
The namespace of the role. |
rules array |
The array of rules associated with this role. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create role task. |
taskStatus string |
The status of the operation. |
Replace a role
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/roles/role-name/namespace-name?cluster_id=:cluster_id"
Content-Type: application/json
{
"metadata": {
"name": "role-name",
"namespace": "namespace-name"
}
"rules": [
{
"apiGroups": [
""
],
"resources": [
"resource"
],
"verbs": [
"get",
"watch",
"..."
]
}
]
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/roles/:id?cluster_id=:cluster_id
Replace a role in a given environment.
| Required Attributes | |
|---|---|
metadata object |
The metadata of the role. |
metadata.name string |
The name of the role. |
metadata.namespace string |
The namespace of the role. |
metadata.namespace string |
The namespace of the role. |
| Optional Attributes | |
|---|---|
rules array |
The array of rules associated with this role. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace role operation. |
taskStatus string |
The status of the operation. |
Delete a role
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/roles/default-token-xxxmt/default?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/roles/:id?cluster_id=:cluster_id
Delete a role from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to delete the role. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete role task. |
taskStatus string |
The status of the operation. |
Role bindings
List (namespace) role bindings
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/rolebindings?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
The above command returns a JSON structured like this:
{
"data": {
"entity": {
"id": "kubeadm:bootstrap-signer-clusterinfo",
"age": "1w5d",
"metadata": {
"creationTimestamp": "2020-09-18T10:46:32.000-04:00",
"name": "kubeadm:bootstrap-signer-clusterinfo",
"namespace": "kube-public",
"uid": "4fcfe5b9-a1c3-4b3b-9cb6-6df4a1da945f"
},
"roleRef": {
"apiGroup": "rbac.authorization.k8s.io",
"kind": "Role",
"name": "kubeadm:bootstrap-signer-clusterinfo"
},
"subjects": [
{
"apiGroup": "rbac.authorization.k8s.io",
"kind": "User",
"name": "system:anonymous"
}
]
},
"fieldTransitions": {},
"operations": []
},
}
GET /services/:service_code/:environment_name/rolebindings?cluster_id=:cluster_id
Retrieve a list of all role bindings in a given environment.
| Attributes | |
|---|---|
id string |
The id of the role binding. |
metadata object |
The metadata of the role binding. |
metadata.creationTimestamp string |
The date of creation of the role binding as a string. |
metadata.name string |
The name of the role binding. |
metadata.namespace string |
The namespace in which the role binding is created. |
metadata.uid object |
The UUID of the role binding. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a role binding
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/rolebindings/rolebinding-name/rolebinding-namespace?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
The above command returns a JSON structured like this:
{
"data": {
"id": "kubeadm:bootstrap-signer-clusterinfo",
"age": "1w5d",
"metadata": {
"creationTimestamp": "2020-09-18T10:46:32.000-04:00",
"name": "kubeadm:bootstrap-signer-clusterinfo",
"namespace": "kube-public",
"uid": "4fcfe5b9-a1c3-4b3b-9cb6-6df4a1da945f"
},
"roleRef": {
"apiGroup": "rbac.authorization.k8s.io",
"kind": "Role",
"name": "kubeadm:bootstrap-signer-clusterinfo"
},
"subjects": [
{
"apiGroup": "rbac.authorization.k8s.io",
"kind": "User",
"name": "system:anonymous"
}
]
},
"fieldTransitions": {},
"operations": []
},
}
GET /services/:service_code/:environment_name/rolebindings/:id?cluster_id=:cluster_id
Retrieve a role binding and all its info in a given environment.
| Attributes | |
|---|---|
id string |
The id of the role binding. |
apiVersion string |
The API version used to retrieve this role binding. |
metadata object |
The metadata of the role binding. |
roleRefobject |
The role to bind. Can reference a Role in the current namespace or a ClusterRole in the global namespace. |
subjects array |
The array of subjects associated with this role binding. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a role binding
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/rolebindings?cluster_id=:cluster_id"
Content-Type: application/json
{
"kind": "Rolebinding",
"metadata": {
"name": "rolebinding-name",
"namespace": "namespace-name"
},
"roleRef": {
"apiGroup": "rbac.authorization.k8s.io",
"kind": "Role",
"name": "role-name"
},
"subjects": [
{
"kind": "ServiceAccount",
"name": "service-account-name",
"namespace": "service-account-namespace"
},
{
"kind": "Group",
"name": "group-name",
"namespace": "group-namespace"
},
{
"kind": "User",
"name": "user-name",
}
]
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/rolebindings?cluster_id=:cluster_id
Create a role binding in a given environment.
| Required Attributes | |
|---|---|
metadata object |
The metadata of the role binding. |
metadata.name string |
The name of the role binding. |
metadata.namespace string |
The namespace of the role binding. |
roleRefobject |
The role to bind. Can reference a Role in the current namespace or a ClusterRole in the global namespace. |
subjectsarray |
Subjects hold references to the objets the role applies to. Can be users, groups, or service accounts. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create role binding task. |
taskStatus string |
The status of the operation. |
Replace a role binding
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/rolebindings/rolebinding-name/namespace-name?cluster_id=:cluster_id"
Content-Type: application/json
{
"metadata": {
"name": "service-account-name",
"namespace": "namespace-name"
},
"roleRef": {
"apiGroup": "",
"kind": "Role",
"name": "role-name"
},
"subjects": [
{
"kind": "ServiceAccount",
"name": "default",
"namespace": "default"
},
{
"kind": "user",
"name": "user1",
}
]
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/rolebindings/:id?cluster_id=:cluster_id
Replace a role binding in a given environment.
| Required Attributes | |
|---|---|
metadata object |
The metadata of the role binding. |
metadata.name string |
The name of the role binding. |
metadata.namespace string |
The namespace of the role binding. |
roleRefobject |
The role to bind. Can reference a Role in the current namespace or a ClusterRole in the global namespace. |
subjectsarray |
Subjects hold references to the objets the role applies to. Can be users, groups, or service accounts. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace role binding operation. |
taskStatus string |
The status of the operation. |
Delete a role binding
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/rolebindings/default-token-xxxmt/default?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
json { "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b", "taskStatus": "PENDING" }DELETE /services/:service_code/:environment_name/rolebindings/:id?cluster_id=:cluster_id
Delete a role binding from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to delete the role binding. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete role binding task. |
taskStatus string |
The status of the operation. |
Releases
List releases
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/releases?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "my-namespace/my-cloudflare",
"name": "my-cloudflare",
"info": {
"first_deployed": "2020-11-03T09:48:49.301166-05:00",
"last_deployed": "2020-11-05T11:24:37.096888-05:00",
"deleted": "",
"description": "Upgrade complete",
"status": "installed",
"notes": "You can connect to the container running cloudflare-dyndns. To open a shell session in the pod run the following:\n..."
},
"chart": {
"metadata": {
"name": "cloudflare-dyndns",
"home": "https://github.com/billimek/billimek-charts/tree/master/charts/cloudflare-dyndns",
"sources": [
"https://github.com/hotio/docker-cloudflare-ddns/",
"https://github.com/billimek/billimek-charts"
],
"version": "2.0.0",
"description": "Dynamic DNS using Cloudflare's DNS Services",
"keywords": [
"cloudflare",
"dynamicdns"
],
"maintainers": [
{
"name": "billimek",
"email": "jeff@billimek.com"
}
],
"icon": "https://www.cloudflare.com/img/cf-facebook-card.png",
"apiVersion": "v1",
"appVersion": "1.0",
"deprecated": false
},
"values": {
"affinity": {},
"cloudflare": {
"detection_mode": "dig-google.com",
"hosts": "somehosts",
"log_level": 1.0,
"record_types": "somerecordtypes",
"sleep_interval": 300.0,
"token": "sometoken",
"user": "someuser",
"zones": "somezones"
},
"image": {
"pullPolicy": "Always",
"repository": "hotio/cloudflare-ddns",
"tag": "latest"
},
"nodeSelector": {},
"replicaCount": 1.0,
"resources": {},
"tolerations": []
}
},
"config": {
"affinity": {},
"cloudflare": {
"detection_mode": "dig-google.com",
"hosts": "somehosts",
"log_level": 1.0,
"record_types": "somerecordtypes",
"sleep_interval": 300.0,
"token": "sometoken",
"user": "someuser",
"zones": "somezones"
},
"image": {
"pullPolicy": "Always",
"repository": "hotio/cloudflare-ddns",
"tag": "latest"
},
"nodeSelector": {},
"replicaCount": 1.0,
"resources": {},
"tolerations": []
},
"version": 10,
"namespace": "my-namespace",
"keepHistory": false,
"chartVersion": "cloudflare-dyndns / 2.0.0"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/releases?cluster_id=:cluster_id
Or
GET /services/:service_code/:environment_name/releases?namespace=default&cluster_id=:cluster_id
Retrieve a list of all releases in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the releases. |
| Optional | |
|---|---|
namespace string |
The namespace to list the release. This needs the exact value. |
| Attributes | |
|---|---|
id string |
The release id, of the form namespace/releaseName. |
name string |
The name of the release. |
info object |
The information about the release. |
info.first_deployed string |
The annotations of the pod. |
info.last_deployed string |
The date of creation of the pod as a string. |
info.deleted string |
The labels associated to the pod. |
info.description string |
The name of the pod. |
info.status string |
The status of the release. Possible values are unknown, installed, uninstalled, superseded, failed, uninstalling, pending-install, pending-upgrade, pending-rollback. |
info.notes string |
The notes linked to the release. |
chartobject |
The information related to the chart of used in the release. |
chart.version string |
The version of the chart. |
chart.metadata object |
The metadata associated to the chart. |
chart.metadata.name string |
The name of the chart. |
chart.metadata.home string |
The home URL for the chart. |
chart.metadata.sources list |
The list of source of the charts. |
chart.metadata.version string |
The version of the chart. |
chart.metadata.description string |
The description of the chart. |
chart.metadata.keywords list |
The list of keywords linked to the chart. |
chart.metadata.maintainers list |
The list of the maintainer contact information. |
chart.metadata.icon string |
The icon URL for the chart. |
chart.metadata.appVersion string |
The version of the application. |
chart.metadata.deprecate bool |
If the chart is deprecated or not of the application. |
config object |
All values that were used to install the release. |
versionstring |
The revision of the release. |
namespacestring |
The namespace to which the release is installed. |
The information is not totally returned in the list. We filter out the manifest portion. We also filter out the files and the templates of the chart details. This information will be present in the GET request for an individual release.
Get release
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/releases/my-namespace/my-cloudflare?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
The above command returns a JSON structured like this:
{
"data": {
"id": "my-namespace/my-cloudflare",
"name": "my-cloudflare",
"info": {
"first_deployed": "2020-11-03T09:48:49.301166-05:00",
"last_deployed": "2020-11-05T19:44:46.775668959Z",
"deleted": "",
"description": "Upgrade complete",
"status": "installed",
"notes": "You can connect to the container running cloudflare-dyndns. To open a shell session in the pod run the following:\n..."
},
"chart": {
"metadata": {
"name": "cloudflare-dyndns",
"home": "https://github.com/billimek/billimek-charts/tree/master/charts/cloudflare-dyndns",
"sources": [
"https://github.com/hotio/docker-cloudflare-ddns/",
"https://github.com/billimek/billimek-charts"
],
"version": "2.0.0",
"description": "Dynamic DNS using Cloudflare's DNS Services",
"keywords": [
"cloudflare",
"dynamicdns"
],
"maintainers": [
{
"name": "billimek",
"email": "jeff@billimek.com"
}
],
"icon": "https://www.cloudflare.com/img/cf-facebook-card.png",
"apiVersion": "v1",
"appVersion": "1.0",
"deprecated": false
},
"templates": [
{
"name": "templates/NOTES.txt",
"data": "WW91I...fScp"
},
{
"name": "templates/_helpers.tpl",
"data": "e3svKi...9Cg=="
},
{
"name": "templates/deployment.yaml",
"data": "YXBpVm...9Cg=="
},
{
"name": "templates/secret.yaml",
"data": "YXBpVmVy...X0="
}
],
"values": {
"affinity": {},
"cloudflare": {
"detection_mode": "dig-google.com",
"hosts": "somehosts",
"log_level": 1.0,
"record_types": "somerecordtypes",
"sleep_interval": 300.0,
"token": "sometoken",
"user": "someuser",
"zones": "somezones"
},
"image": {
"pullPolicy": "Always",
"repository": "hotio/cloudflare-ddns",
"tag": "latest"
},
"nodeSelector": {},
"replicaCount": 1.0,
"resources": {},
"tolerations": []
},
"files": [
{
"name": ".helmignore",
"data": "IyBQYX...b2oK"
},
{
"name": "README.md",
"data": "IyBE..4K"
}
]
},
"manifest": "---\n# Source: cloudflare-dyndns/templates/secret.yaml\napiVersion: v1\n...",
"config": {
"affinity": {},
"cloudflare": {
"detection_mode": "dig-google.com",
"hosts": "somehosts",
"log_level": 1.0,
"record_types": "somerecordtypes",
"sleep_interval": 300.0,
"token": "sometoken",
"user": "someuser",
"zones": "somezones"
},
"image": {
"pullPolicy": "Always",
"repository": "hotio/cloudflare-ddns",
"tag": "latest"
},
"nodeSelector": {},
"replicaCount": 1.0,
"resources": {},
"tolerations": []
},
"version": 11,
"namespace": "my-namespace",
"keepHistory": false,
"chartVersion": "cloudflare-dyndns / 2.0.0"
}
}
GET /services/:service_code/:environment_name/releases?cluster_id=:cluster_id
Retrieve a release in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the releases. |
| Attributes | |
|---|---|
id string |
The release id, of the form namespace/releaseName. |
name string |
The name of the release. |
info object |
The information about the release. |
info.first_deployed string |
The date the release was created. |
info.last_deployed string |
The date the release was last updated. |
info.deleted string |
The labels associated to the pod |
info.description string |
Description of the release's status. |
info.status string |
The status of the release. Possible values are unknown, installed, uninstalled, superseded, failed, uninstalling, pending-install, pending-upgrade, pending-rollback. |
info.notes string |
The notes linked to the release. |
chartobject |
The information related to the chart used to install the release. |
chart.version string |
The version of the chart. |
chart.metadata object |
The metadata associated to the chart. |
chart.metadata.name string |
The name of the chart. |
chart.metadata.home string |
The home URL for the chart. |
chart.metadata.sources list |
The list of source of the charts. |
chart.metadata.version string |
The version of the chart. |
chart.metadata.description string |
The description of the chart. |
chart.metadata.keywords list |
The list of keywords linked to the chart. |
chart.metadata.maintainers list |
The list of the maintainer contact information. |
chart.metadata.icon string |
The icon URL for the chart. |
chart.metadata.appVersion string |
The version of the application. |
chart.metadata.deprecate bool |
If the chart is deprecated or not of the application. |
chart.templates list |
The list of templates contained inside the chart. |
chart.templates.name string |
The path name of the template inside the chart. |
chart.templates.data string |
The contents of the template. This is a base64 encoded string. |
chart.files list |
The list of files contained inside the chart. These are not YAML files unlike the templates. |
chart.files.name string |
The path name of the file inside the chart. |
chart.files.data string |
The contents of the file. This is a base64 encoded string. |
manifest string |
The YAML Kubernetes resources created by the Helm templating. |
config object |
All values that were used to install the release. |
versionstring |
The revision of the release. |
namespacestring |
The namespace to which the release is installed. |
Rollback release to previous revision
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/releases/pspensieri/aerospike-1579797954&operation=rollback&cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
The above command returns a JSON structured like this:
{
"data": {
"name": "aerospike-1579797954",
"version": 8,
"info": {
"deleted": "",
"description": "Rollback to 6",
"status": "deployed",
...
...
},
"taskId": "13943961-4a2c-4439-b7c9-05113d3b593a",
"taskStatus": "SUCCESS"
}
POST /services/:service_code/:environment_name/releases/:id?operation=rollback&cluster_id=:cluster_id
Rollback a release in a given environment to the previous revision.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to rollback the release. |
| Attributes | |
|---|---|
data Object |
The release object. See get release for a description of the release attributes. |
taskId string |
The task id related to the pod rollback. |
taskStatus string |
The status of the operation. |
Upgrade release
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/releases/my-namespace/my-aerospike?operation=upgrade&cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
-d "request_body"
Request body examples:
// Change to the latest version of a chart
{
"upgradeChart": {
"name": "aerospike",
"repository": {
"url": "https://aerospike.github.io/aerospike-kubernetes-enterprise"
}
}
}
// Change to a specific version of a chart
{
"upgradeChart": {
"name": "aerospike",
"version": "4.9.0",
"repository": {
"url": "https://aerospike.github.io/aerospike-kubernetes-enterprise"
}
}
}
// Change the values for the latest version
{
"upgradeChart": {
"name": "aerospike",
"repository": {
"url": "https://aerospike.github.io/aerospike-kubernetes-enterprise"
}
},
"upgradeValues": "\"replicaCount\": 3"
}
The above commands return JSON structured like this:
{
"taskId": "c50390c7-9d5b-4af4-a2da-e2a2678a83e8",
"taskStatus": "SUCCESS"
}
POST /services/:service_code/:environment_name/releases/:id?operation=upgrade&cluster_id=:cluster_id
Upgrade a release in a given environment.
| Required | |
|---|---|
upgradeChart Object |
The chart object that should be used to ugprade the release. |
upgradeChart.name string |
The chart name. |
repository Object |
The repository object to which the chart belongs. |
repository.url string |
The repository's URL. |
| Optional | |
|---|---|
upgradeChart.version string |
The chart version that should be used to upgrade the chart. If none is provided, the latest is used. |
upgradeChart.values string |
YAML structured text that will overwrite the default values for the upgrade/installation of the chart. |
| Attributes | |
|---|---|
taskId string |
The task id related to the pod upgrade. |
taskStatus string |
The status of the operation. |
Uninstall a release
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/releases/pspensieri/aerospike-1579797954&operation=uninstall&cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
-d "request_body"
Request body example:
{
"keepHistory": true
}
The above command returns a JSON structured like this:
{
"data": {
"version": 0,
"keepHistory": false
},
"taskId": "938f11b2-b37d-459e-8cf2-dea05c4d8f63",
"taskStatus": "SUCCESS"
}
POST /services/:service_code/:environment_name/releases/:id?operation=uninstall&cluster_id=:cluster_id
Uninstall a release in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to uninstall the release. |
| Optional | |
|---|---|
keepHistory bool |
If true, will keep release history after uninstalling. Defaults to false. |
| Attributes | |
|---|---|
version string |
The uninstalled release's revision. Revision 0 indicated it was uninstalled. |
keepHistory string |
The keepHistory value used when uninstalling the chart. |
taskId string |
The task id related to the pod uninstall. |
taskStatus string |
The status of the operation. |
Charts
List charts
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/charts?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "helm-stable/aerospike",
"name": "aerospike",
"description": "A Helm chart for Aerospike in Kubernetes",
"version": "0.3.3",
"license": "",
"deprecated": false,
"repository": {
"url": "https://kubernetes-charts.storage.googleapis.com",
"name": "helm-stable",
"kind": 0,
"official": false,
"displayName": "Stable",
"repositoryId": "3cc327ae-9403-4521-9b71-f9a41d5f86c8",
"organizationName": "helm",
"verifiedPublisher": false,
"organizationDisplayName": "Helm"
},
"packageId": "c4b6ad70-898d-4093-bec8-089d5f48daeb",
"displayName": "",
"normalizedName": "aerospike",
"appVersion": "v4.5.0.5",
"logoImageId": "50bcf132-ff98-4f9a-9e6a-0c0b06649e48",
"logoImageUrl": "https://artifacthub.io/image/50bcf132-ff98-4f9a-9e6a-0c0b06649e48"
}
],
"metadata": {
"pageSize": 50,
"pageCurrent": 1,
"recordCount": 148
}
}
GET /services/:service_code/:environment_name/charts?cluster_id=:cluster_id
Retrieve a list of all charts in a given environment. To get more chart details, such as available versions, the chart's readme and list of maintainers, see the GET request for an individual chart.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the charts. |
| Attributes | |
|---|---|
| Attributes | |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
id string |
The id for the chart, of the form repositoryName/chartName. |
name string |
The chart name. |
description string |
The chart description. |
version string |
The latest chart version. |
license string |
The chart's license. |
deprecated boolean |
True if the chart is deprecated. |
repository object |
The chart's parent repository. |
repoository.url string |
The repository URL. |
repository.name string |
The repository name. |
repository.kind integer |
The repository kind, where {0: Helm chart, 1: Falco rule, 2: OPA policy, 3: OLM operator }. |
repository.official boolean |
True if it is an official repository. That is, if the publisher owns the software deployed by the package. |
repository.displayName string |
The repository's display name. |
repository.repositoryId UUID |
The UUID of the repository. |
repository.organizationName string |
The name of the organization that owns the repository. |
repository.organizationDisplayName string |
The display name of the organization that owns the repository. |
repository.verifiedPublisher boolean |
True if the publisher owns the repository. |
packageId UUID |
The UUID of the package, given by ArtifactHub. |
displayName string |
The chart's display name. |
normalizedName string |
The chart's normalized name. |
appVersion string |
The chart's app version. |
logoImageId UUID |
The UUID of the package's logo, given by ArtifactHub. |
logoImageUrl string |
The URL for the chart's logo. |
Get chart
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/charts/k8s-at-home/cloudflare-dyndns?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
The above command returns a JSON structured like this:
{
"data": {
"keywords": [
"cloudflare",
"dynamicdns"
],
"maintainers": [
{
"name": "billimek",
"email": "jeff@billimek.com"
}
],
"links": [
{
"url": "https://github.com/hotio/docker-cloudflare-ddns/",
"name": "source"
},
{
"url": "https://github.com/billimek/billimek-charts",
"name": "source"
}
],
"homeUrl": "https://github.com/billimek/billimek-charts/tree/master/charts/cloudflare-dyndns",
"availableVersions": [
{
"version": "1.0.0",
"createdAt": 1576998322
},
{
"version": "2.0.0",
"createdAt": 1578688072
}
],
"readMe": "# Dynamic DNS using Cloudflare's DNS Services\n...",
"id": "k8s-at-home/cloudflare-dyndns",
"name": "cloudflare-dyndns",
"description": "Dynamic DNS using Cloudflare's DNS Services",
"version": "2.0.0",
"license": "",
"deprecated": false,
"repository": {
"url": "https://k8s-at-home.com/charts/",
"name": "k8s-at-home",
"kind": 0,
"official": false,
"displayName": "charts",
"repositoryId": "9b40a3b3-ed2a-405f-8919-3b824d4f661d",
"organizationName": "k8s-at-home",
"verifiedPublisher": true,
"organizationDisplayName": "k8s@home"
},
"packageId": "a6cd6148-977a-4852-8761-80234f39d90b",
"displayName": "",
"normalizedName": "cloudflare-dyndns",
"appVersion": "1.0",
"logoImageId": "3a0eac41-21b4-4a1b-b127-c7e70123eda8",
"logoImageUrl": "https://artifacthub.io/image/3a0eac41-21b4-4a1b-b127-c7e70123eda8"
}
}
GET /services/:service_code/:environment_name/charts/:id?cluster_id=cluster_id
Retrieve a specific chart in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the chart. |
| Attributes | |
|---|---|
id string |
The id for the chart, of the form repositoryName/chartName. |
name string |
The chart name. |
description string |
The chart description. |
version string |
The latest chart version. |
license string |
The chart's license. |
deprecated boolean |
True if the chart is deprecated. |
repository object |
The chart's parent repository. |
repoository.url string |
The repository URL. |
repository.name string |
The repository name. |
repository.kind integer |
The repository kind, where {0: Helm chart, 1: Falco rule, 2: OPA policy, 3: OLM operator }. |
repository.official boolean |
True if it is an official repository. That is, if the publisher owns the software deployed by the package. |
repository.displayName string |
The repository's display name. |
repository.repositoryId UUID |
The UUID of the repository. |
repository.organizationName string |
The name of the organization that owns the repository. |
repository.organizationDisplayName string |
The display name of the organization that owns the repository. |
repository.verifiedPublisher boolean |
True if the publisher owns the repository. |
packageId UUID |
The UUID of the package, given by ArtifactHub. |
displayName string |
The chart's display name. |
normalizedName string |
The chart's normalized name. |
appVersion string |
The chart's app version. |
logoImageId UUID |
The UUID of the package's logo, given by ArtifactHub. |
logoImageUrl string |
The URL for the chart's logo. |
keywords Array[string] |
The chart's keywords. |
maintainers Array[Object] |
The names and emails of chart maintainers. |
homeUrl Array[Object] |
The chart's home URL. |
availableVersions Array[Object] |
The available chart versions and their created dates. |
Install chart
curl --request POST </span>
--url https://cloudmc_endpoint/api/v2/services/a_service/an_environment/charts?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1 </span>
--header 'MC-Api-Key: your_api_key' </span>
--data '{
"namespace": "my-namespace",
"releaseName": "my-aerospike",
"name": "aerospike",
"version": "5.0.0",
"values": ""
"repository": {
"url": "https://aerospike.github.io/aerospike-kubernetes-enterprise"
}
}'
The above command returns a JSON structured like this:
{
"taskId": "ef70cafa-0544-4709-a66a-c68595ee105a",
"taskStatus": "SUCCESS"
}
POST /services/:service_code/:environment_name/charts?cluster_id=:cluster_id
Install a chart in a given environment.
| Required Query Parameters | |
|---|---|
cluster_id string |
The id of the cluster in which to install the chart. |
| Required Attributes | |
|---|---|
cluster_id string |
The id of the cluster in which to install the chart. |
namespace string |
The namespace in which the chart will be installed. |
releaseName string |
The desired release name. |
name string |
The chart name. |
repository object |
The chart's parent repository from which it should be installed. |
repoository.url string |
The repository URL. |
| Optional Attributes | |
|---|---|
version string |
The chart version to be installed. Defaults to the latest version if left blank. |
values string |
The values used to install the chart. Must be a valid Yaml format. If not provided, the chart's default values will be used. |
insecureServerboolean |
True if accessing the chart requires an unsecured connection. |
Images
Images are virtual machine images that have a virtual disk which contains a bootable operating system.
List images
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/images"
The above command returns a JSON structured like this:
{
"data": [
{
"archiveSizeBytes": "10843137280",
"creationTimestamp": "2019-05-14T16:49:57.269-07:00",
"description": "Debian, Debian GNU/Linux, 9 (stretch), amd64 built on 20190514",
"diskSizeGb": "10",
"family": "debian-9",
"guestOsFeatures": [
{
"type": "VIRTIO_SCSI_MULTIQUEUE"
}
],
"kind": "compute#image",
"labelFingerprint": "42WmSpB8rSM=",
"licenseCodes": [
"1000205"
],
"licenses": [
"https://www.googleapis.com/compute/v1/projects/debian-cloud/global/licenses/debian-9-stretch"
],
"rawDisk": {
"containerType": "TAR",
"source": ""
},
"selfLink": "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-9-stretch-v20190514",
"sourceType": "RAW",
"status": "READY",
"vendorFamily": "debian-cloud",
"shortName": "Debian",
"iconUrl": "/rest/services/assets/gcp/os_logo/debian.png",
"id": "2447790134347098827",
"name": "debian-9-stretch-v20190514"
},
{
"archiveSizeBytes": "16469314560",
"creationTimestamp": "2019-05-15T19:01:21.060-07:00",
"description": "CentOS, CentOS, 7, x86_64 built on 20190515",
"diskSizeGb": "10",
"family": "centos-7",
"kind": "compute#image",
"labelFingerprint": "42WmSpB8rSM=",
"licenseCodes": [
"1000207"
],
"licenses": [
"https://www.googleapis.com/compute/v1/projects/centos-cloud/global/licenses/centos-7"
],
"rawDisk": {
"containerType": "TAR",
"source": ""
},
"selfLink": "https://www.googleapis.com/compute/v1/projects/centos-cloud/global/images/centos-7-v20190515",
"sourceType": "RAW",
"status": "READY",
"vendorFamily": "centos-cloud",
"shortName": "CentOS",
"iconUrl": "/rest/services/assets/gcp/os_logo/centos.png",
"id": "4658005417542122143",
"name": "centos-7-v20190515"
}
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/images
Retrieve a list of available images.
| Attributes | |
|---|---|
archiveSizeBytesstring |
Size of the image tar.gz archive stored in Google Cloud Storage (in bytes). |
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
descriptionstring |
An optional description of this resource. |
diskSizeGbstring |
Size of the image when restored onto a persistent disk (in GB). |
familystring |
The name of the image family to which this image belongs. |
kindstring |
Type of the resource. |
labelFingerprintstring |
A base64-encoded string. A hash of the label's contents and used for optimistic locking. |
licenseCodesArray[integer] |
License codes indicating which licenses are attached to this image.. |
licensesArray[URI] |
Any applicable license URI. |
rawDiskObject |
The parameters of the raw disk image. |
selfLinkstring |
Server-defined URL for this resource. |
sourceTypestring |
The type of the image used to create this disk. The default and only value is RAW. |
statusstring |
The status of the image. An image can be used to create other resources, such as instances, only after the image has been successfully created and the status is set to READY. Possible values are FAILED, PENDING, or READY. |
vendorFamilystring |
Image family's vendor name. |
shortNamestring |
A short version of the OS image's name. |
iconUrlstring |
Icon representing the OS image. |
idUUID |
The image's id. |
namestring |
The image's name. |
Retrieve an image
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/images/4658005417542122143"
The above command returns a JSON structured like this:
{
"data": {
"archiveSizeBytes": "16469314560",
"creationTimestamp": "2019-05-15T19:01:21.060-07:00",
"description": "CentOS, CentOS, 7, x86_64 built on 20190515",
"diskSizeGb": "10",
"family": "centos-7",
"kind": "compute#image",
"labelFingerprint": "42WmSpB8rSM=",
"licenseCodes": [
"1000207"
],
"licenses": [
"https://www.googleapis.com/compute/v1/projects/centos-cloud/global/licenses/centos-7"
],
"rawDisk": {
"containerType": "TAR",
"source": ""
},
"selfLink": "https://www.googleapis.com/compute/v1/projects/centos-cloud/global/images/centos-7-v20190515",
"sourceType": "RAW",
"status": "READY",
"vendorFamily": "centos-cloud",
"shortName": "CentOS",
"iconUrl": "/rest/services/assets/gcp/os_logo/centos.png",
"id": "4658005417542122143",
"name": "centos-7-v20190515"
}
}
GET /services/:service_code/:environment_name/images/:id
Retrieve information about an image.
| Attributes | |
|---|---|
archiveSizeBytesstring |
Size of the image tar.gz archive stored in Google Cloud Storage (in bytes). |
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
descriptionstring |
An optional description of this resource. |
diskSizeGbstring |
Size of the image when restored onto a persistent disk (in GB). |
familystring |
The name of the image family to which this image belongs. |
kindstring |
Type of the resource. |
labelFingerprintstring |
A base64-encoded string. A hash of the label's contents and used for optimistic locking. |
licenseCodesArray[integer] |
License codes indicating which licenses are attached to this image. |
licensesArray[URI] |
Any applicable license URI. |
rawDiskObject |
The parameters of the raw disk image. |
selfLinkstring |
Server-defined URL for this resource. |
sourceTypestring |
The type of the image used to create this disk. The default and only value is RAW. |
statusstring |
The status of the image. An image can be used to create other resources, such as instances, only after the image has been successfully created and the status is set to READY. Possible values are FAILED, PENDING, or READY. |
vendorFamilystring |
Image family's vendor name. |
shortNamestring |
A short version of the OS image's name. |
iconUrlstring |
Icon representing the OS image. |
idUUID |
The image's id. |
namestring |
The image's name. |
Regions
A region is a geographical area where a resource is located. Regions contains multiple Zones.
List regions
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/regions"
The above command returns a JSON structured like this:
{
"data": [
{
"creationTimestamp": "1969-12-31T16:00:00.000-08:00",
"description": "northamerica-northeast1",
"id": "1330",
"kind": "compute#region",
"name": "northamerica-northeast1",
"quotas": [
{
"limit": 24.0,
"metric": "CPUS",
"usage": 0.0
},
{
"limit": 4096.0,
"metric": "DISKS_TOTAL_GB",
"usage": 40.0
}
],
"selfLink": "https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/northamerica-northeast1",
"status": "UP",
"zones": [
"https://www.googleapis.com/compute/v1/projects/test-area-oox/zones/northamerica-northeast1-a",
"https://www.googleapis.com/compute/v1/projects/test-area-oox/zones/northamerica-northeast1-b",
"https://www.googleapis.com/compute/v1/projects/test-area-oox/zones/northamerica-northeast1-c"
]
},
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/regions
Retrieve a list of available regions, filtered by the service connection's policies.
| Attributes | |
|---|---|
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
descriptionstring |
An optional description of this resource. |
idUUID |
The region's id. |
kindstring |
Type of the resource. |
namestring |
The region's name. |
quotasArray[object] |
Quotas assigned to this region. |
selfLinkstring |
Server-defined URL for this resource. |
statusstring |
tatus of the region, either UP or DOWN. |
zonesArray[URL] |
A list of zones available in this region, in the form of resource URLs. |
Retrieve a region
curl -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/gcp/test-area/regions/1330"
The above command returns a JSON structured like this:
{
"data": {
"creationTimestamp": "1969-12-31T16:00:00.000-08:00",
"description": "northamerica-northeast1",
"id": "1330",
"kind": "compute#region",
"name": "northamerica-northeast1",
"quotas": [
{
"limit": 24.0,
"metric": "CPUS",
"usage": 0.0
},
{
"limit": 4096.0,
"metric": "DISKS_TOTAL_GB",
"usage": 40.0
}
],
"selfLink": "https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/northamerica-northeast1",
"status": "UP",
"zones": [
"https://www.googleapis.com/compute/v1/projects/test-area-oox/zones/northamerica-northeast1-a",
"https://www.googleapis.com/compute/v1/projects/test-area-oox/zones/northamerica-northeast1-b",
"https://www.googleapis.com/compute/v1/projects/test-area-oox/zones/northamerica-northeast1-c"
]
}
}
GET /services/:service_code/:environment_name/regions/:id
Retrieve information about a region.
| Attributes | |
|---|---|
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
descriptionstring |
An optional description of this resource. |
idUUID |
The region's id. |
kindstring |
Type of the resource. |
namestring |
The region's name. |
quotasArray[object] |
Quotas assigned to this region. |
selfLinkstring |
Server-defined URL for this resource. |
statusstring |
tatus of the region, either UP or DOWN. |
zonesArray[URL] |
A list of zones available in this region, in the form of resource URLs. |
Kubernetes plugin
The Kubernetes plugin provides endpoints to carrying out operations on CloudMC Kubernetes entities.
Namespaces
List namespaces
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/namespaces"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "auth",
"metadata": {},
"spec": {},
"status": {}
}
],
"metadata": {
"recordCount": 3
}
}
GET /services/:service_code/:environment_name/namespaces
Retrieve a list of all namespaces in a given environment.
| Attributes | |
|---|---|
id string |
The id of the namespace. |
metadata object |
The metadata of the namespace. |
specobject |
The specification describes the attributes on a namespace. |
statusobject |
The status information of the namespace. |
Get a namespace
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/namespaces/cert-manager"
The above command returns a JSON structured like this:
{
"data": {
"id": "cert-manager",
"apiVersion": "v1",
"kind": "Namespace",
"metadata": {},
"spec": {},
"status": {}
}
}
GET /services/:service_code/:environment_name/namespaces/:id
Retrieve a namespace and all its info in a given environment.
| Attributes | |
|---|---|
id string |
The id of the namespace. |
apiVersion string |
APIVersion defines the versioned schema of this representation of a namespace object. |
metadata object |
The metadata of the namespace. |
specobject |
The specification describes the attributes on a namespace. |
statusobject |
The status information of the namespace. |
Create a namespace
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/namespaces"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Namespace",
"metadata": {
"name": "test-namespace"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/namespaces
Create a namespace in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the namespace. |
metadata object |
The metadata of the namespace. |
metadata.name string |
The name of the namespace. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create namespace task. |
taskStatus string |
The status of the operation. |
Delete a namespace
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/namespaces/test-namespace"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/namespaces/:id
Delete a namespace from a given environment.
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete namespaces task. |
taskStatus string |
The status of the operation. |
Workloads
Pods
List pods
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/pods"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "my-aerospike-0/default",
"metadata": {
"annotations": {
"checksum/config": "0e07919467cc16f2c07ac99d0036405deafa06f7d3b430215915470b3a6ca631"
},
"creationTimestamp": "2020-01-20T09:35:02.000-05:00",
"generateName": "my-aerospike-",
"labels": {
"app": "aerospike",
"controller-revision-hash": "my-aerospike-d9969496d",
"release": "my-aerospike",
"statefulset.kubernetes.io/pod-name": "my-aerospike-0"
},
"name": "my-aerospike-0",
"namespace": "default",
"ownerReferences": [
{
"apiVersion": "apps/v1",
"blockOwnerDeletion": true,
"controller": true,
"kind": "StatefulSet",
"name": "my-aerospike",
"uid": "0b00ea3d-3b92-11ea-935e-025000000001"
}
],
"resourceVersion": "95058",
"selfLink": "/api/v2/namespaces/default/pods/my-aerospike-0",
"uid": "0b055519-3b92-11ea-935e-025000000001"
},
"spec": {
"containers": [
{
"image": "aerospike/aerospike-server:4.5.0.5",
"imagePullPolicy": "IfNotPresent",
"name": "my-aerospike",
"ports": [
{
"containerPort": 3000,
"name": "clients",
"protocol": "TCP"
},
{
"containerPort": 3002,
"name": "mesh",
"protocol": "TCP"
},
{
"containerPort": 3003,
"name": "info",
"protocol": "TCP"
}
],
"readinessProbe": {
"failureThreshold": 3,
"initialDelaySeconds": 15,
"periodSeconds": 10,
"successThreshold": 1,
"tcpSocket": {
"port": 3000
},
"timeoutSeconds": 1
},
"resources": {},
"terminationMessagePath": "/dev/termination-log",
"terminationMessagePolicy": "File",
"volumeMounts": [
{
"mountPath": "/etc/aerospike",
"name": "config-volume"
},
{
"mountPath": "/var/run/secrets/kubernetes.io/serviceaccount",
"name": "default-token-64jnc",
"readOnly": true
}
]
}
],
"dnsPolicy": "ClusterFirst",
"enableServiceLinks": true,
"hostname": "my-aerospike-0",
"nodeName": "docker-desktop",
"priority": 0,
"restartPolicy": "Always",
"schedulerName": "default-scheduler",
"securityContext": {},
"serviceAccount": "default",
"serviceAccountName": "default",
"subdomain": "my-aerospike",
"terminationGracePeriodSeconds": 30,
"tolerations": [
{
"effect": "NoExecute",
"key": "node.kubernetes.io/not-ready",
"operator": "Exists",
"tolerationSeconds": 300
},
{
"effect": "NoExecute",
"key": "node.kubernetes.io/unreachable",
"operator": "Exists",
"tolerationSeconds": 300
}
],
"volumes": [
{
"configMap": {
"defaultMode": 420,
"items": [
{
"key": "aerospike.conf",
"path": "aerospike.conf"
}
],
"name": "my-aerospike"
},
"name": "config-volume"
},
{
"name": "default-token-64jnc",
"secret": {
"defaultMode": 420,
"secretName": "default-token-64jnc"
}
}
]
},
"status": {
"conditions": [
{
"lastTransitionTime": "2020-01-20T09:35:02.000-05:00",
"status": "True",
"type": "Initialized"
},
{
"lastTransitionTime": "2020-01-21T15:05:33.000-05:00",
"status": "True",
"type": "Ready"
},
{
"lastTransitionTime": "2020-01-21T15:05:33.000-05:00",
"status": "True",
"type": "ContainersReady"
},
{
"lastTransitionTime": "2020-01-20T09:35:02.000-05:00",
"status": "True",
"type": "PodScheduled"
}
],
"containerStatuses": [
{
"containerID": "docker://b45436d2978cb8e6186b22c24d3b819cabd00921a009b30c2599a935d0c69b49",
"image": "aerospike/aerospike-server:4.5.0.5",
"imageID": "docker-pullable://aerospike/aerospike-server@sha256:5bec98d46c8a521003e1c5b6f015713f2663384dd66916cca696e4e1c142c539",
"lastState": {
"terminated": {
"containerID": "docker://5e4b23c07269669f302c7c6a446399e59d553cf1a622094c1d3cc64b6f65a9e0",
"exitCode": 255,
"finishedAt": "2020-01-21T15:04:35.000-05:00",
"reason": "Error",
"startedAt": "2020-01-20T10:28:19.000-05:00"
}
},
"name": "my-aerospike",
"ready": true,
"restartCount": 2,
"state": {
"running": {
"startedAt": "2020-01-21T15:05:16.000-05:00"
}
}
}
],
"hostIP": "192.168.65.3",
"phase": "Running",
"podIP": "10.1.0.129",
"qosClass": "BestEffort",
"startTime": "2020-01-20T09:35:02.000-05:00"
}
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/pods
Retrieve a list of all pods in a given environment.
| Attributes | |
|---|---|
id string |
The id of the pod. |
metadata object |
The metadata of the pod. |
metadata.annotations map |
The annotations of the pod. |
metadata.creationTimestamp string |
The date of creation of the pod as a string. |
metadata.labels map |
The labels associated to the pod. |
metadata.name string |
The name of the pod. |
metadata.namespace string |
The namespace in which the pod is created. |
metadata.uid object |
The UUID of the pod. |
specobject |
The specification used to create and run the pod. |
spec.containerstring |
The name of the container running. |
statusobject |
The status information of the pod. |
status.phasestring |
The status of the pod. Possible statuses are Running, Pending, Succeeded, Unknown and Failed. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a pod
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/pods/my-aerospike-0/default"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "my-aerospike-0/default",
"metadata": {
"annotations": {
"checksum/config": "0e07919467cc16f2c07ac99d0036405deafa06f7d3b430215915470b3a6ca631"
},
"creationTimestamp": "2020-01-20T09:35:02.000-05:00",
"generateName": "my-aerospike-",
"labels": {
"app": "aerospike",
"controller-revision-hash": "my-aerospike-d9969496d",
"release": "my-aerospike",
"statefulset.kubernetes.io/pod-name": "my-aerospike-0"
},
"name": "my-aerospike-0",
"namespace": "default",
"ownerReferences": [
{
"apiVersion": "apps/v1",
"blockOwnerDeletion": true,
"controller": true,
"kind": "StatefulSet",
"name": "my-aerospike",
"uid": "0b00ea3d-3b92-11ea-935e-025000000001"
}
],
"resourceVersion": "95058",
"selfLink": "/api/v2/namespaces/default/pods/my-aerospike-0",
"uid": "0b055519-3b92-11ea-935e-025000000001"
},
"spec": {
"containers": [
{
"image": "aerospike/aerospike-server:4.5.0.5",
"imagePullPolicy": "IfNotPresent",
"name": "my-aerospike",
"ports": [
{
"containerPort": 3000,
"name": "clients",
"protocol": "TCP"
},
{
"containerPort": 3002,
"name": "mesh",
"protocol": "TCP"
},
{
"containerPort": 3003,
"name": "info",
"protocol": "TCP"
}
],
"readinessProbe": {
"failureThreshold": 3,
"initialDelaySeconds": 15,
"periodSeconds": 10,
"successThreshold": 1,
"tcpSocket": {
"port": 3000
},
"timeoutSeconds": 1
},
"resources": {},
"terminationMessagePath": "/dev/termination-log",
"terminationMessagePolicy": "File",
"volumeMounts": [
{
"mountPath": "/etc/aerospike",
"name": "config-volume"
},
{
"mountPath": "/var/run/secrets/kubernetes.io/serviceaccount",
"name": "default-token-64jnc",
"readOnly": true
}
]
}
],
"dnsPolicy": "ClusterFirst",
"enableServiceLinks": true,
"hostname": "my-aerospike-0",
"nodeName": "docker-desktop",
"priority": 0,
"restartPolicy": "Always",
"schedulerName": "default-scheduler",
"securityContext": {},
"serviceAccount": "default",
"serviceAccountName": "default",
"subdomain": "my-aerospike",
"terminationGracePeriodSeconds": 30,
"tolerations": [
{
"effect": "NoExecute",
"key": "node.kubernetes.io/not-ready",
"operator": "Exists",
"tolerationSeconds": 300
},
{
"effect": "NoExecute",
"key": "node.kubernetes.io/unreachable",
"operator": "Exists",
"tolerationSeconds": 300
}
],
"volumes": [
{
"configMap": {
"defaultMode": 420,
"items": [
{
"key": "aerospike.conf",
"path": "aerospike.conf"
}
],
"name": "my-aerospike"
},
"name": "config-volume"
},
{
"name": "default-token-64jnc",
"secret": {
"defaultMode": 420,
"secretName": "default-token-64jnc"
}
}
]
},
"status": {
"conditions": [
{
"lastTransitionTime": "2020-01-20T09:35:02.000-05:00",
"status": "True",
"type": "Initialized"
},
{
"lastTransitionTime": "2020-01-21T15:05:33.000-05:00",
"status": "True",
"type": "Ready"
},
{
"lastTransitionTime": "2020-01-21T15:05:33.000-05:00",
"status": "True",
"type": "ContainersReady"
},
{
"lastTransitionTime": "2020-01-20T09:35:02.000-05:00",
"status": "True",
"type": "PodScheduled"
}
],
"containerStatuses": [
{
"containerID": "docker://b45436d2978cb8e6186b22c24d3b819cabd00921a009b30c2599a935d0c69b49",
"image": "aerospike/aerospike-server:4.5.0.5",
"imageID": "docker-pullable://aerospike/aerospike-server@sha256:5bec98d46c8a521003e1c5b6f015713f2663384dd66916cca696e4e1c142c539",
"lastState": {
"terminated": {
"containerID": "docker://5e4b23c07269669f302c7c6a446399e59d553cf1a622094c1d3cc64b6f65a9e0",
"exitCode": 255,
"finishedAt": "2020-01-21T15:04:35.000-05:00",
"reason": "Error",
"startedAt": "2020-01-20T10:28:19.000-05:00"
}
},
"name": "my-aerospike",
"ready": true,
"restartCount": 2,
"state": {
"running": {
"startedAt": "2020-01-21T15:05:16.000-05:00"
}
}
}
],
"hostIP": "192.168.65.3",
"phase": "Running",
"podIP": "10.1.0.129",
"qosClass": "BestEffort",
"startTime": "2020-01-20T09:35:02.000-05:00"
}
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/pods/:id
Retrieve a pod and all its info in a given environment.
| Attributes | |
|---|---|
id string |
The id of the pod. |
metadata object |
The metadata of the pod. |
metadata.annotations map |
The annotations of the pod. |
metadata.creationTimestamp string |
The date of creation of the pod as a string. |
metadata.labels map |
The labels associated to the pod. |
metadata.name string |
The name of the pod. |
metadata.namespace string |
The namespace in which the pod is created. |
metadata.uid object |
The UUID of the pod. |
specobject |
The specification used to create and run the pod. |
spec.containerstring |
The name of the container running. |
statusobject |
The status information of the pod. |
status.phasestring |
The status of the pod. Possible statuses are Running, Pending, Succeeded, Unknown and Failed. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a pod
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/pods"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Pod",
"metadata": {
"name": "edgar-allen-pod",
"namespace": "default"
},
"spec": {
"containers": [
{
"image": "nginx",
"name": "nginx"
}
]
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/pods
Create a pod in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the pod. |
metadata object |
The metadata of the pod. |
metadata.name string |
The name of the pod. |
specobject |
The specification used to create and run the pod. |
spec.container.imagestring |
The docker image name. |
spec.container.namestring |
The (unique) name of the container specified as a DNS_LABEL. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the pod is created |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create pod task. |
taskStatus string |
The status of the operation. |
Replace a pod
curl -X PUT \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/pods/edgar-allen-pod/default"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Pod",
"metadata": {
"name": "edgar-allen-pod",
"namespace": "default"
},
"spec": {
"containers": [
{
"image": "nginx",
"name": "nginx"
}
]
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/pods/:id
Replace a pod in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the pod. |
metadata object |
The metadata of the pod. |
metadata.name string |
The name of the pod. |
specobject |
The specification used to replace and run the pod. |
spec.container.imagestring |
The docker image name. |
spec.container.namestring |
The (unique) name of the container specified as a DNS_LABEL. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the pod is replaced. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace pod task. |
taskStatus string |
The status of the operation. |
Delete a pod
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/pods/my-aerospike-0/default"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/pods/:id
Delete a pod from a given environment.
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete pod task. |
taskStatus string |
The status of the operation. |
Deployments
List deployments
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/deployments"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "apm-server-1585600296-apm-server/monitoring",
"deploymentStatus": "Available",
"readyRatio": "1/1",
"metadata": {},
"spec": {},
"status": {}
}
],
"metadata": {
"recordCount": 9
}
}
GET /services/:service_code/:environment_name/deployments
Retrieve a list of all deployments in a given environment.
| Attributes | |
|---|---|
id string |
The id of the deployment. |
metadata object |
The metadata of the deployment. |
metadata.name string |
The name of the deployment. |
metadata.namespace string |
The namespace in which the deployment is created. |
metadata.uid object |
The UUID of the deployment. |
images object |
The container images within a deployment. |
specobject |
The specification used to create and run the deployment. |
statusobject |
The status information of the deployment. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a deployment
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/deployments/test-aerospike/auth"
The above command returns a JSON structured like this:
{
"data": {
"id": "apm-server-1585600296-apm-server/monitoring",
"deploymentStatus": "Available",
"readyRatio": "1/1",
"metadata": {},
"spec": {},
"status": {}
}
}
GET /services/:service_code/:environment_name/deployments/:id
Retrieve a deployment and all its info in a given environment.
| Attributes | |
|---|---|
id string |
The id of the deployment. |
deplomentStatusobject |
The status information of the deployment. |
readyRatio object |
The ready replicas to total replicas ratio of this deployment set. |
metadata object |
The metadata of the deployment. |
specobject |
The specification used to create and run the deployment. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a deployment
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/deployments"
Content-Type: application/json
{
"apiVersion": "apps/v1",
"kind": "Deployment",
"metadata": {
"name": "api-test-deployment-name",
"namespace": "default"
},
"spec": {
"selector": {
"matchLabels": {
"app": "nginx"
}
},
"template": {
"metadata": {
"labels": {
"app": "nginx"
}
},
"spec": {
"containers": [
{
"name": "nginx",
"image": "nginx"
}
]
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/deployments
Create a deployment in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the deployment. |
metadata object |
The metadata of the deployment. |
metadata.name string |
The name of the deployment. |
specobject |
The specification used to replace and run the deployment. |
spec.selectorobject |
The label query over the deployment's set of resources. |
spec.templateobject |
The data a deployment's pod should have when replaced. |
spec.specobject |
The specification used to replace and run the pod(s) within the deployment. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the deployment is replaced. |
spec.selector.matchLabelsobject |
The key value pairs retrieved by a label query from a deployment. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace deployment task. |
taskStatus string |
The status of the operation. |
Replace a deployment
curl -X PUT \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/deployments/deployment-name/default"
Content-Type: application/json
{
"apiVersion": "apps/v1",
"kind": "Deployment",
"metadata": {
"name": "deployment-name",
"namespace": "default"
},
"spec": {
"selector": {
"matchLabels": {
"app": "nginx"
}
},
"template": {
"metadata": {
"labels": {
"app": "nginx"
}
},
"spec": {
"containers": [
{
"name": "nginx",
"image": "nginx"
}
]
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/deployments/:id
Replace a deployment in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the deployment. |
metadata object |
The metadata of the deployment. |
metadata.name string |
The name of the deployment. |
specobject |
The specification used to create and run the deployment. |
spec.selectorobject |
The label query over the deployment's set of resources. |
spec.templateobject |
The data a deployment's pod should have when created. |
spec.specobject |
The specification used to create and run the pod(s) within the deployment. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the deployment is created. |
spec.selector.matchLabelsobject |
The key value pairs retrieved by a label query from a deployment. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create deployment task. |
taskStatus string |
The status of the operation. |
Delete a deployment
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/deployments/dex/auth"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/deployments/:id
Delete a deployment from a given environment.
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete deployment task. |
taskStatus string |
The status of the operation. |
Daemon Sets
List daemon sets
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/daemonsets"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "canal/kube-system",
"metadata": {},
"spec": {},
"status": {}
}
],
"metadata": {
"recordCount": 9
}
}
GET /services/:service_code/:environment_name/daemonsets
Retrieve a list of all daemon sets in a given environment.
| Attributes | |
|---|---|
id string |
The id of the daemon set. |
metadata object |
The metadata of the daemon set. |
specobject |
The specification used to create and run the daemon set. |
statusobject |
The status information of the daemon set. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a daemon set
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/daemonsets/test-aerospike/auth"
The above command returns a JSON structured like this:
{
"data": {
"id": "canal/kube-system",
"metadata": {},
"spec": {},
"status": {}
}
}
GET /services/:service_code/:environment_name/daemonsets/:id
Retrieve a daemon set and all its info in a given environment.
| Attributes | |
|---|---|
id string |
The id of the daemon set. |
metadata object |
The metadata of the daemon set. |
specobject |
The specification used to create and run the daemon set. |
statusobject |
The status information of the daemon set. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a daemon set
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/daemonsets"
Content-Type: application/json
{
"apiVersion": "apps/v1",
"kind": "DaemonSet",
"metadata": {
"name": "daemonset-name",
"namespace": "default"
},
"spec": {
"selector": {
"matchLabels": {
"name": "fluentd-elasticsearch"
}
},
"template": {
"metadata": {
"labels": {
"name": "fluentd-elasticsearch"
}
},
"spec": {
"containers": [
{
"name": "fluentd-elasticsearch",
"image": "quay.io/fluentd_elasticsearch/fluentd:v2.5.2"
}
]
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/daemonsets
Create a daemon set in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the daemon set. |
metadata object |
The metadata of the daemon set. |
metadata.name string |
The name of the daemon set. |
specobject |
The specification used to create and run the daemon set. |
spec.selectorobject |
The label query over the daemon set's resources. |
spec.templateobject |
The data a daemon set's pod should have when created. |
spec.specobject |
The specification used to create and run the pod(s) within the daemon set. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the daemon set is created. |
spec.selector.matchLabelsobject |
The key value pairs retrieved by a label query from a daemon set. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create daemon set task. |
taskStatus string |
The status of the operation. |
Replace a daemon set
curl -X PUT \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/daemonsets/daemonset-name/default"
Content-Type: application/json
{
"apiVersion": "apps/v1",
"kind": "DaemonSet",
"metadata": {
"name": "daemonset-name",
"namespace": "default"
},
"spec": {
"selector": {
"matchLabels": {
"name": "fluentd-elasticsearch"
}
},
"template": {
"metadata": {
"labels": {
"name": "fluentd-elasticsearch"
}
},
"spec": {
"containers": [
{
"name": "fluentd-elasticsearch",
"image": "quay.io/fluentd_elasticsearch/fluentd:v2.5.2"
}
]
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/daemonsets/:id
Replace a daemon set in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the daemon set. |
metadata object |
The metadata of the daemon set. |
metadata.name string |
The name of the daemon set. |
specobject |
The specification used to replace and run the daemon set. |
spec.selectorobject |
The label query over the daemon set's resources. |
spec.templateobject |
The data a daemon set's pod should have when replaced. |
spec.specobject |
The specification used to create and run the pod(s) within the daemon set. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the daemon set is replaced. |
spec.selector.matchLabelsobject |
The key value pairs retrieved by a label query from a daemon set. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace daemon set task. |
taskStatus string |
The status of the operation. |
Delete a daemon set
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/daemonsets/nginx-ingress-controller/ingress-nginx"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/daemonsets/:id
Delete a daemon set from a given environment.
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete daemon set task. |
taskStatus string |
The status of the operation. |
Stateful Sets
List stateful sets
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/statefulsets"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "test-aerospike/auth",
"images": ["aerospike/aerospike-server:4.5.0.5"],
"metadata": {},
"spec": {},
"status": {}
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/statefulsets
Retrieve a list of all stateful sets in a given environment.
| Attributes | |
|---|---|
id string |
The id of the stateful set. |
metadata object |
The metadata of the stateful set. |
specobject |
The specification used to create and run the stateful set. |
statusobject |
The status information of the stateful set. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a stateful set
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/statefulsets/test-aerospike/auth"
The above command returns a JSON structured like this:
{
"data": {
"id": "test-aerospike/auth",
"replicaRatio": "1 / 1",
"images": ["aerospike/aerospike-server:4.5.0.5"],
"apiVersion": "apps/v1",
"kind": "StatefulSet",
"metadata": {},
"spec": {},
"status": {}
}
}
GET /services/:service_code/:environment_name/statefulsets/:id
Retrieve a stateful set and all its info in a given environment.
| Attributes | |
|---|---|
id string |
The id of the stateful set. |
metadata object |
The metadata of the stateful set. |
specobject |
The specification used to create and run the stateful set. |
statusobject |
The status information of the stateful set. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a stateful set
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/statefulsets"
Content-Type: application/json
{
"apiVersion": "apps/v1",
"kind": "StatefulSet",
"metadata": {
"name": "stateful-set-name",
"namespace": "default"
},
"spec": {
"selector": {
"matchLabels": {
"app": "nginx"
}
},
"template": {
"metadata": {
"labels": {
"app": "nginx"
}
},
"spec": {
"containers": [
{
"name": "nginx",
"image": "k8s.gcr.io/nginx-slim:0.8"
}
]
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/statefulsets
Create a stateful set in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the stateful set. |
metadata object |
The metadata of the stateful set. |
metadata.name string |
The name of the stateful set. |
specobject |
The specification used to create and run the stateful set. |
spec.selectorobject |
The label query over the stateful set's of resources. |
spec.templateobject |
The data a stateful set's pod should have when created. |
spec.specobject |
The specification used to create and run the pod(s) within the stateful set. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the stateful set is created. |
spec.selector.matchLabelsobject |
The key value pairs retrieved by a label query from a stateful set. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create stateful set task. |
taskStatus string |
The status of the operation. |
Replace a stateful set
curl -X PUT \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/statefulsets/stateful-set-name/default"
Content-Type: application/json
{
"apiVersion": "apps/v1",
"kind": "StatefulSet",
"metadata": {
"name": "stateful-set-name",
"namespace": "default"
},
"spec": {
"selector": {
"matchLabels": {
"app": "nginx"
}
},
"template": {
"metadata": {
"labels": {
"app": "nginx"
}
},
"spec": {
"containers": [
{
"name": "nginx",
"image": "k8s.gcr.io/nginx-slim:0.8"
}
]
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/statefulsets/:id
Replace a stateful set in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the stateful set. |
metadata object |
The metadata of the stateful set. |
metadata.name string |
The name of the stateful set. |
specobject |
The specification used to replaced and run the stateful set. |
spec.selectorobject |
The label query over the stateful set's of resources. |
spec.templateobject |
The data a stateful set's pod should have when replaced. |
spec.specobject |
The specification used to replace and run the pod(s) within the stateful set. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the stateful set is replaced. |
spec.selector.matchLabelsobject |
The key value pairs retrieved by a label query from a stateful set. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace stateful set task. |
taskStatus string |
The status of the operation. |
Delete a stateful set
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/statefulsets/my-aerospike/default"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/statefulsets/:id
Delete a stateful set from a given environment.
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete stateful set task. |
taskStatus string |
The status of the operation. |
Networking
Services
List services
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/services"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "alaintest-aerospike/default",
"ports": ["3000/TCP", "3002/TCP"],
"type": "ClusterIP",
"metadata": {},
"spec": {},
"status": {
"loadBalancer": {}
}
},
{
"id": "alertmanager-operated/monitoring",
"ports": ["9093/TCP", "9094/TCP", "9094/UDP"],
"type": "NodePort",
"apiVersion": "v1",
"kind": "Service",
"metadata": {},
"spec": {},
"status": {
"loadBalancer": {}
}
}
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/services
Retrieve a list of all services in a given environment.
| Attributes | |
|---|---|
id string |
The id of the service |
metadata object |
The metadata of the service |
metadata.name string |
The name of the service |
metadata.namespace string |
The namespace in which the service is created |
metadata.uid object |
The UUID of the service |
type object |
The container images within a service |
portsobject |
The list of ports that are exposed by this service |
specobject |
The attributes that a user creates on a service |
spec.selectorobject |
The keys and values corresponding to pod labels, used to determine where service traffic will be routed |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a service
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/services/test-aerospike/auth"
The above command returns a JSON structured like this:
{
"data": {
"id": "test-aerospike/auth",
"ports": ["3000/TCP", "3002/TCP"],
"type": "ClusterIP",
"apiVersion": "v1",
"kind": "Service",
"metadata": {},
"spec": {},
"status": {
"loadBalancer": {}
}
}
}
GET /services/:service_code/:environment_name/services/:id
Retrieve a service and all its info in a given environment.
| Attributes | |
|---|---|
id string |
The id of the service |
metadata object |
The metadata of the service |
metadata.name string |
The name of the service |
metadata.namespace string |
The namespace in which the service is created |
metadata.uid object |
The UUID of the service |
type object |
The container images within a service |
portsobject |
The list of ports that are exposed by this service |
specobject |
The attributes that a user creates on a service |
spec.selectorobject |
The keys and values corresponding to pod labels, used to determine where service traffic will be routed |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a service
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/services"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Service",
"metadata": {
"name": "service-name",
"namespace": "default"
},
"spec": {
"ports": [
{
"port": 3000,
"protocol": "TCP"
}
],
"type": "ClusterIP"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/services
Create a service in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the service. |
metadata object |
The metadata of the service. |
metadata.name string |
The name of the service. |
specobject |
The specification used to create and run the service. |
spec.portsobject |
The list of ports that are exposed by this service. |
spec.typeobject |
The type of service (ClusterIP, NodePort, ExternalName or LoadBalancer) |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the service is created. |
spec.selectorobject |
The label query over the service's set of resources. |
spec.selector.matchLabelsobject |
The key value pairs retrieved by a label query from a service. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create service task. |
taskStatus string |
The status of the operation. |
Replace a service
curl -X PUT \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/services/service-name/default"
Request body example:
{
"type": "LoadBalancer",
"ports": [
"4000/TCP"
],
"apiVersion": "v1",
"kind": "Service",
"metadata": {
"creationTimestamp": "2020-08-13T11:05:00.000-04:00",
"name": "service-name",
"namespace": "default",
"resourceVersion": "170742452",
"selfLink": "/api/v2/namespaces/default/services/service-name",
"uid": "a84c8fea-f9d9-47ab-8e58-37059e9f18bd"
},
"spec": {
"clusterIP": "10.245.44.45",
"externalTrafficPolicy": "Cluster",
"ports": [
{
"nodePort": 31167,
"port": 3000,
"protocol": "TCP",
"targetPort": 306
}
],
"sessionAffinity": "ClientIP",
"sessionAffinityConfig": {
"clientIP": {
"timeoutSeconds": 10555
}
},
"type": "LoadBalancer"
},
"status": {
"loadBalancer": {}
}
}
PUT /services/:service_code/:environment_name/services/:id
Replace a service in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the service. |
metadata object |
The metadata of the service. |
metadata.name string |
The name of the service. |
specobject |
The specification used to create and run the service. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace service task. |
taskStatus string |
The status of the operation. |
Delete a service
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/services/test-service/default"
DELETE /services/:service_code/:environment_name/services/:id
Delete a service from a given environment.
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete service task. |
taskStatus string |
The status of the operation. |
Ingresses V1Beta1
Ingress v1beta1 has been deprecated in this API as of 26.7.0 following the removal of support by kubernetes. Please use the ingress v1 api instead.
<!--
Delete an ingress V1Beta1
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/ingresses/test-ingress/default"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/ingresses/:id
Delete an ingress V1Beta1 from a given environment.
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete ingress task. |
taskStatus string |
The status of the operation. |
Ingresses V1
List ingresses V1
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/ingressesv1"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "cloudmc/cmc-stg",
"endpoint": "http://cmc.cloudmc-staging-endpoint.com",
"service": {
"port": "8080",
"name": "cloudmc"
},
"metadata": {
"annotations": {},
"creationTimestamp": "2019-07-11T10:00:18.000-04:00",
"generation": 10,
"name": "cloudmc",
"namespace": "cmc-stg",
"resourceVersion": "143213903",
"uid": "376bc4c5-a3e4-11e9-b6bd-02006e76001e"
},
"spec": {
"rules": [],
"tls": []
},
"status": {
"loadBalancer": {}
}
},
{
"id": "cm-acme-http-solver-75png/auth",
"endpoint": "http://cmc.cloudmc-staging-endpoint.com",
"service": {
"port": "8089",
"name": "cm-acme-http-solver-2x5gv"
},
"metadata": {
"annotations": {},
"creationTimestamp": "2020-06-24T11:00:49.000-04:00",
"generateName": "cm-acme-http-solver-",
"generation": 1,
"labels": {
"acme.cert-manager.io/http-domain": "1965164889",
"acme.cert-manager.io/http-token": "820448657",
"acme.cert-manager.io/http01-solver": "true"
},
"name": "cm-acme-http-solver-75png",
"namespace": "auth",
"ownerReferences": [],
"resourceVersion": "143213968",
"uid": "48720f48-f2bc-45fc-95c5-60cae8ffe11e"
},
"spec": {
"rules": []
},
"status": {
"loadBalancer": {}
}
}
]
}
GET /services/:service_code/:environment_name/ingressesv1
Retrieve a list of all ingresses V1 in a given environment.
| Attributes | |
|---|---|
id string |
The id of the ingress. |
endpoint string |
The endpoint of the ingress. |
service object |
The service associated with the ingress. |
service.port string |
The port of the service associated with the ingress. |
service.name string |
The name of the service associated with the ingress. |
metadata object |
The metadata of the ingress. |
metadata.name string |
The name of the ingress. |
metadata.namespace string |
The namespace in which the ingress is created. |
metadata.labels object |
The labels associated with the ingress. |
metadata.uid object |
The UUID of the ingress. |
specobject |
The attributes that a user specifies for an ingress. |
Note that the list is not complete, since it is referring to the kubernetes api details.
Get an ingress V1
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/ingressesv1/cloudmc/cmc-stg"
The above command returns a JSON structured like this:
{
"data": {
"id": "cloudmc/cmc-stg",
"endpoint": "http://cmc.cloudmc-staging-endpoint.com",
"service": {
"port": "8080",
"name": "cloudmc"
},
"metadata": {
"annotations": {},
"creationTimestamp": "2019-07-11T10:00:18.000-04:00",
"generation": 10,
"name": "cloudmc",
"namespace": "cmc-stg",
"resourceVersion": "143213903",
"uid": "376bc4c5-a3e4-11e9-b6bd-02006e76001e"
},
"spec": {
"rules": [],
"tls": []
},
"status": {
"loadBalancer": {}
}
}
}
GET /services/:service_code/:environment_name/ingressesv1/:id
Retrieve an ingress V1 and all its info in a given environment.
| Attributes | |
|---|---|
id string |
The id of the ingress. |
endpoint string |
The endpoint of the ingress. |
service object |
The service associated with the ingress. |
service.port string |
The port of the service associated with the ingress. |
service.name string |
The name of the service associated with the ingress. |
metadata object |
The metadata of the ingress. |
metadata.name string |
The name of the ingress. |
metadata.namespace string |
The namespace in which the ingress is created. |
metadata.labels object |
The labels associated with the ingress. |
metadata.uid object |
The UUID of the ingress. |
specobject |
The attributes that a user specifies for an ingress. |
Note that the list is not complete, since it is referring to the kubernetes api details.
Create an ingress V1
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/ingressesv1"
Content-Type: application/json
{
"apiVersion": "networking.k8s.io/v1",
"kind": "Ingress",
"metadata": {
"name": "ingress-name",
"namespace": "default",
"annotations": {
"nginx.ingress.kubernetes.io/rewrite-target": "/"
}
},
"spec": {
"rules": [
{
"hostname": "endpoint.com",
"http": {
"paths": [
{
"path": "/testpath",
"pathType": "Prefix",
"backend": {
"service": {
"name": "test",
"port": {
"number": 80
}
}
}
}
]
}
}
]
}
}
POST /services/:service_code/:environment_name/ingressesv1
Create an ingress V1 in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the ingress. |
metadata object |
The metadata of the ingress. |
metadata.name string |
The name of the ingress. |
specobject |
The specification used to create and run the ingress. |
spec.rulesobject |
The list of host rules used to configure the ingress. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the ingress is created. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create ingress task. |
taskStatus string |
The status of the operation. |
Replace an ingress V1
curl -X PUT \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/ingressesv1/ingress-name/default"
Request body example:
{
"endpoint": "http://my-endpoint.com",
"service": {
"port": "6556",
"name": "test"
},
"apiVersion": "networking.k8s.io/v1",
"kind": "Ingress",
"metadata": {
"creationTimestamp": "2020-08-13T14:13:42.000-04:00",
"generation": 3,
"name": "ingress-name",
"namespace": "default",
"resourceVersion": "170302224",
"uid": "c67e6a6a-2b07-4976-8b3d-2ec9fd91ae5d"
},
"spec": {
"rules": [
{
"host": "my-endpoint.com",
"http": {
"paths": [
{
"backend": {
"service": {
"name": "test",
"port": {
"number": 6556
}
}
},
"path": "/testpath"
}
]
}
}
]
},
"status": {
"loadBalancer": {
"ingress": [
{
"hostname": "hostname-worker-01"
},
{
"hostname": "hostname-worker-02"
},
{
"hostname": "hostname-worker-03"
},
{
"hostname": "hostname-worker-04"
}
]
}
}
}
PUT /services/:service_code/:environment_name/ingressesv1/:id
Replace an ingress V1 in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the ingress. |
metadata object |
The metadata of the ingress. |
metadata.name string |
The name of the ingress. |
specobject |
The specification used to create and run the ingress. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace ingress task. |
taskStatus string |
The status of the operation. |
Delete an ingress V1
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/ingressesv1/test-ingress/default"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/ingressesv1/:id
Delete an ingress V1 from a given environment.
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete ingress task. |
taskStatus string |
The status of the operation. |
Configuration
Config Maps
List config maps
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/configmaps"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "coredns/kube-system",
"data": {
"Corefile": ".:53 {\n errors\n health\n kubernetes cluster.local in-addr.arpa ip6.arpa {\n pods insecure\n upstream\n fallthrough in-addr.arpa ip6.arpa\n }\n prometheus :9153\n forward . /etc/resolv.conf\n cache 30\n loop\n reload\n loadbalance\n import custom/*.override\n}\nimport custom/*.server\n"
},
"metadata": {}
}
],
"metadata": {
"recordCount": 4
}
}
GET /services/:service_code/:environment_name/configmaps
Retrieve a list of all config maps in a given environment.
| Attributes | |
|---|---|
id string |
The id of the config map. |
apiVersion string |
The API version used to retrieve this config map. |
metadata object |
The metadata of the config map. |
Get a config map
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/configmaps/cert-manager-cainjector-leader-election/kube-system"
The above command returns a JSON structured like this:
{
"data": {
"id": "cert-manager-cainjector-leader-election/kube-system",
"apiVersion": "v1",
"kind": "ConfigMap",
"metadata": {}
}
}
GET /services/:service_code/:environment_name/configmaps/:id
Retrieve a config map and all its info in a given environment.
| Attributes | |
|---|---|
id string |
The id of the config map. |
apiVersion string |
The API version used to retrieve this config map. |
metadata object |
The metadata of the config map. |
Create a config map
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/configmaps"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "ConfigMap",
"metadata": {
"name": "game-demo"
},
"data": {
"player_initial_lives": "3",
"ui_properties_file_name": "user-interface.properties",
"game.properties": "enemy.types=aliens,monsters\nplayer.maximum-lives=5\n",
"user-interface.properties": "color.good=purple\ncolor.bad=yellow\nallow.textmode=true\n"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/configmaps
Create a config map in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the config map. |
metadata object |
The metadata of the config map. |
metadata.name string |
The name of the config map. |
dataobject |
The non-confidential data (in key-value pairs) stored in the config map. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the config map is created |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create config maps task. |
taskStatus string |
The status of the operation. |
Replace a config map
curl -X PUT \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/configmaps/game-demo/default"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "ConfigMap",
"metadata": {
"name": "game-demo",
"namespace": "default"
},
"data": {
"player_initial_lives": "5",
"ui_properties_file_name": "user-interface.properties",
"game.properties": "enemy.types=aliens,monsters\nplayer.maximum-lives=5\n",
"user-interface.properties": "color.good=purple\ncolor.bad=yellow\nallow.textmode=true\n"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/configmaps/:id
Replace a config map in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the config map. |
metadata object |
The metadata of the config map. |
metadata.name string |
The name of the config map. |
dataobject |
The non-confidential data (in key-value pairs) stored in the config map. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the config map is replaced. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace config maps task. |
taskStatus string |
The status of the operation. |
Delete a config map
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/configmaps/cert-manager-cainjector-leader-election/kube-system"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/configmaps/:id
Delete a config map from a given environment.
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete config map task. |
taskStatus string |
The status of the operation. |
Secrets
List secrets
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/secrets"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "default-token-xxxmt/default",
"apiVersion": "v1",
"encodedData": {
"ca.crt": "LS0tLS...",
"namespace": "a3ViZS1zeXN0ZW0=",
"token": "ZXlKa..."
},
"kind": "Secret",
"metadata": {},
"type": "kubernetes.io/service-account-token"
}
],
"metadata": {
"recordCount": 100
}
}
GET /services/:service_code/:environment_name/secrets
Retrieve a list of all secrets in a given environment.
| Attributes | |
|---|---|
id string |
The id of the secret. |
apiVersion string |
The API version used to retrieve the secret. |
encodedDataobject |
The base64 encoded data stored in the secret. |
metadata object |
The metadata of the secret. |
type string |
A string used to facilitate programmatic handling of a secret's data. |
Get a secret
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/secrets/default-token-xxxmt/default"
The above command returns a JSON structured like this:
{
"data": {
"id": "default-token-xxxmt/default",
"apiVersion": "v1",
"encodedData": {
"ca.crt": "LS0tLS...",
"namespace": "a3ViZS1zeXN0ZW0=",
"token": "ZXlKa..."
},
"kind": "Secret",
"metadata": {},
"type": "kubernetes.io/service-account-token"
}
}
GET /services/:service_code/:environment_name/secrets/:id
Retrieve a secret and all its info in a given environment.
| Attributes | |
|---|---|
id string |
The id of the secret. |
apiVersion string |
The API version used to retrieve the secret. |
encodedDataobject |
The base64 encoded data stored in the secret. |
metadata object |
The metadata of the secret. |
type string |
A string used to facilitate programmatic handling of a secret's data. |
Create a secret
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/secrets"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Secret",
"metadata": {
"name": "mysecret"
},
"type": "Opaque",
"stringData": {
"username": "my-username",
"password": "my-password"
}
}
# OR
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/secrets"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Secret",
"metadata": {
"name": "mysecret"
},
"type": "Opaque",
"encodedData": {
"username": "YWRtaW4=",
"password": "MWYyZDFlMmU2N2Rm"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/secrets
Create a secret in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the secret. |
metadata object |
The metadata of the secret. |
metadata.name string |
The name of the secret. |
One of the following two attributes is also required.
| Attributes | |
|---|---|
encodedDataobject |
The base64 encoded data stored in the secret. |
stringDataobject |
The non-base64 encoded data to be encoded when the secret is created. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the secret is created. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create secret task. |
taskStatus string |
The status of the operation. |
Replace a secret
curl -X PUT \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/secrets/my-secret/shhh"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Secret",
"metadata": {
"name": "mysecret",
"namespace": "shhh"
},
"type": "Opaque",
"stringData": {
"username": "my-username",
"password": "my-new-password"
}
}
# OR
curl -X PUT \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/secrets/my-secret/shhh"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Secret",
"metadata": {
"name": "mysecret"
},
"type": "Opaque",
"encodedData": {
"username": "YWRtaW4=",
"password": "MWYyFDZlMmU2N2Rm"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/secrets/:id
Replace a secret in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the secret. |
metadata object |
The metadata of the secret. |
metadata.name string |
The name of the secret. |
One of the following two attributes is also required.
| Attributes | |
|---|---|
encodedDataobject |
The base64 encoded data stored in the secret. |
stringDataobject |
The non-base64 encoded data to be encoded when the secret is replaced. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the secret is replaced. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace secret task. |
taskStatus string |
The status of the operation. |
Delete a secret
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/secrets/default-token-xxxmt/default"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/secrets/:id
Delete a secret from a given environment.
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete secret task. |
taskStatus string |
The status of the operation. |
Storage
Storage Classes
List storage classes
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/storageclasses"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "rook-ceph-block",
"isDefault": true,
"allowVolumeExpansion": true,
"metadata": {
"annotations": {
"storageclass.kubernetes.io/is-default-class": "true"
},
"creationTimestamp": "2020-04-20T16:08:54.000-04:00",
"name": "rook-ceph-block",
"resourceVersion": "107033002",
"selfLink": "/apis/storage.k8s.io/v1/storageclasses/rook-ceph-block",
"uid": "f289c0e6-3f20-4274-8cb8-5db8b34dece6"
},
"parameters": {
"clusterID": "rook-ceph",
"csi.storage.k8s.io/controller-expand-secret-name": "rook-csi-rbd-provisioner",
"csi.storage.k8s.io/controller-expand-secret-namespace": "rook-ceph",
"csi.storage.k8s.io/fstype": "ext4",
"csi.storage.k8s.io/node-stage-secret-name": "rook-csi-rbd-node",
"csi.storage.k8s.io/node-stage-secret-namespace": "rook-ceph",
"csi.storage.k8s.io/provisioner-secret-name": "rook-csi-rbd-provisioner",
"csi.storage.k8s.io/provisioner-secret-namespace": "rook-ceph",
"imageFeatures": "layering",
"imageFormat": "2",
"pool": "replicapool"
},
"provisioner": "rook-ceph.rbd.csi.ceph.com",
"reclaimPolicy": "Delete",
"volumeBindingMode": "Immediate"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/storageclasses
Retrieve a list of all storage classes in a given environment.
| Attributes | |
|---|---|
id string |
The id of the storage class. This is the name of the resource. |
isDefault boolean |
Whether or not the storage class is the default one. |
allowVolumeExpansion boolean |
Whether not the storage class allows for expandable volumes. |
metadata object |
The metadata of the storage class. |
parameters object |
The parameters for the storage provisioner. These are storage provisioner specific and you will likely have to read external documentation. |
provisioner string |
The provisioner for the storage class. |
reclaimPolicy string |
The default volume reclaim policy for this storage class. You have a choice between Reclaim or Delete. |
volumeBindingMode string |
The default volume binding model for this storage class. You have a choice between Immediate or WaitForFirstConsumer. |
Get a storage class
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/storageclasses/rook-ceph-block"
The above command returns a JSON structured like this:
{
"data": {
"id": "rook-ceph-block",
"isDefault": true,
"allowVolumeExpansion": true,
"metadata": {
"annotations": {
"storageclass.kubernetes.io/is-default-class": "true"
},
"creationTimestamp": "2020-04-20T16:08:54.000-04:00",
"name": "rook-ceph-block",
"resourceVersion": "107033002",
"selfLink": "/apis/storage.k8s.io/v1/storageclasses/rook-ceph-block",
"uid": "f289c0e6-3f20-4274-8cb8-5db8b34dece6"
},
"parameters": {
"clusterID": "rook-ceph",
"csi.storage.k8s.io/controller-expand-secret-name": "rook-csi-rbd-provisioner",
"csi.storage.k8s.io/controller-expand-secret-namespace": "rook-ceph",
"csi.storage.k8s.io/fstype": "ext4",
"csi.storage.k8s.io/node-stage-secret-name": "rook-csi-rbd-node",
"csi.storage.k8s.io/node-stage-secret-namespace": "rook-ceph",
"csi.storage.k8s.io/provisioner-secret-name": "rook-csi-rbd-provisioner",
"csi.storage.k8s.io/provisioner-secret-namespace": "rook-ceph",
"imageFeatures": "layering",
"imageFormat": "2",
"pool": "replicapool"
},
"provisioner": "rook-ceph.rbd.csi.ceph.com",
"reclaimPolicy": "Delete",
"volumeBindingMode": "Immediate"
}
}
GET /services/:service_code/:environment_name/storageclasses/:id
Retrieve a storage class and all its info in a given environment.
| Attributes | |
|---|---|
id string |
The id of the storage class. This is the name of the resource |
isDefault boolean |
Whether or not the storage class is the default one |
allowVolumeExpansion boolean |
Whether not the storage class allows for expandable volumes. |
metadata object |
The metadata of the storage class. |
parameters object |
The parameters for the storage provisioner. These are storage provisioner specific and you will likely have to read external documentation. |
provisioner string |
The provisioner for the storage class |
reclaimPolicy string |
The default volume reclaim policy for this storage class. You have a choice between Reclaim or Delete. |
volumeBindingMode string |
The default volume binding model for this storage class. You have a choice between Immediate or WaitForFirstConsumer. |
Create a storage class
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/storageclasses"
Content-Type: application/json
{
"apiVersion": "storage.k8s.io/v1",
"kind": "StorageClass",
"metadata": {
"name": "local-storage-name"
},
"provisioner": "kubernetes.io/no-provisioner",
"volumeBindingMode": "WaitForFirstConsumer"
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/storageclasses
Create a storage class in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the storage class. |
metadata object |
The metadata of the storage class. |
metadata.name string |
The name of the storage class. |
provisioner string |
The provisioner for the storage class |
volumeBindingMode string |
The default volume binding model for this storage class. You have a choice between Immediate or WaitForFirstConsumer. |
| Optional Attributes | |
|---|---|
reclaimPolicy string |
The default volume reclaim policy for this storage class. You have a choice between Reclaim or Delete. |
parameters object |
The parameters for the storage provisioner. These are storage provisioner specific and you will likely have to read external documentation. |
allowVolumeExpansion boolean |
Whether not the storage class allows for expandable volumes. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create stateful set task. |
taskStatus string |
The status of the operation. |
Replace a storage class
curl -X PUT \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/storageclasses/rook-ceph-block"
Content-Type: application/json
{
"apiVersion": "storage.k8s.io/v1",
"metadata": {
"name": "hostpath"
},
"provisioner": "docker.io/hostpath"
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/storageclasses/:id
Replace a storage class in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the storage class. |
metadata object |
The metadata of the storage class. |
metadata.name string |
The name of the storage class. |
provisionerobject |
The type of provisioner. |
| Optional Attributes | |
|---|---|
reclaimPolicy string |
Dynamically provisioned PersistentVolumes of this storage class are created with this reclaimPolicy. Defaults to Delete. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace storage class task. |
taskStatus string |
The status of the operation. |
Delete a storage class
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/storageclasses/rook-ceph-block
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/storageclasses/:id
Delete a storage class from a given environment.
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete storage class task. |
taskStatus string |
The status of the operation. |
Persistent volumes
List persistent volumes
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumes"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "pvc-05097a93-120d-45d2-aaab-0f273849fccd",
"metadata": {
"annotations": {
"pv.kubernetes.io/provisioned-by": "rook-ceph.rbd.csi.ceph.com"
},
"creationTimestamp": "2020-07-03T09:12:17.000-04:00",
"finalizers": ["kubernetes.io/pv-protection"],
"name": "pvc-05097a93-120d-45d2-aaab-0f273849fccd",
"resourceVersion": "147569183",
"selfLink": "/api/v2/persistentvolumes/pvc-05097a93-120d-45d2-aaab-0f273849fccd",
"uid": "2e20a8fb-d90c-4c39-acd8-7007f85e2d8e"
},
"spec": {
"accessModes": ["ReadWriteOnce"],
"capacity": {
"storage": "8Gi"
},
"claimRef": {
"apiVersion": "v1",
"kind": "PersistentVolumeClaim",
"name": "data-cmc-cluster-zookeeper-1",
"namespace": "cmc-kafka",
"resourceVersion": "147569124",
"uid": "05097a93-120d-45d2-aaab-0f273849fccd"
},
"csi": {
"driver": "rook-ceph.rbd.csi.ceph.com",
"fsType": "ext4",
"nodeStageSecretRef": {
"name": "rook-csi-rbd-node",
"namespace": "rook-ceph"
},
"volumeAttributes": {
"clusterID": "rook-ceph",
"imageFeatures": "layering",
"imageFormat": "2",
"pool": "replicapool",
"storage.kubernetes.io/csiProvisionerIdentity": "1593101040137-8081-rook-ceph.rbd.csi.ceph.com"
},
"volumeHandle": "0001-0009-rook-ceph-0000000000000001-d11d2a4d-bd2e-11ea-b56e-7a7db811cab1"
},
"persistentVolumeReclaimPolicy": "Delete",
"storageClassName": "rook-ceph-block",
"volumeMode": "Filesystem"
},
"status": {
"phase": "Bound"
}
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/persistentvolumes
Retrieve a list of all persistent volumes in a given environment.
| Attributes | |
|---|---|
id string |
The id of the persistent volume. This is the name of the resource. |
metadata object |
The metadata of the persistent volume. |
spec object |
The specification of the persistent volume. |
spec.accessModes string |
The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes). |
spec.capacity.storage string |
Storage capacity of the persistent volume. |
spec.persistentVolumeReclaimPolicy string |
One of Retain (manual reclamation), Recycle (basic scrub) or Delete (associated storage asset such as AWS EBS, GCE PD, Azure Disk, or OpenStack Cinder volume is deleted). |
spec.storageClassName string |
Storage class associated to the volume. |
spec.capacity.volumeMode string |
If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device. |
status.phase string |
Volume is in one of the following phases: Available, Bound, Released or Failed. |
Get a persistent volume
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumes/pvc-05097a93-120d-45d2"
The above command returns a JSON structured like this:
{
"id": "pvc-05097a93-120d-45d2",
"metadata": {
"annotations": {
"pv.kubernetes.io/provisioned-by": "rook-ceph.rbd.csi.ceph.com"
},
"creationTimestamp": "2020-07-03T09:12:17.000-04:00",
"finalizers": ["kubernetes.io/pv-protection"],
"name": "pvc-05097a93-120d-45d2-aaab-0f273849fccd",
"resourceVersion": "147569183",
"selfLink": "/api/v2/persistentvolumes/pvc-05097a93-120d-45d2-aaab-0f273849fccd",
"uid": "2e20a8fb-d90c-4c39-acd8-7007f85e2d8e"
},
"spec": {
"accessModes": ["ReadWriteOnce"],
"capacity": {
"storage": "8Gi"
},
"claimRef": {
"apiVersion": "v1",
"kind": "PersistentVolumeClaim",
"name": "data-cmc-cluster-zookeeper-1",
"namespace": "cmc-kafka",
"resourceVersion": "147569124",
"uid": "05097a93-120d-45d2-aaab-0f273849fccd"
},
"csi": {
"driver": "rook-ceph.rbd.csi.ceph.com",
"fsType": "ext4",
"nodeStageSecretRef": {
"name": "rook-csi-rbd-node",
"namespace": "rook-ceph"
},
"volumeAttributes": {
"clusterID": "rook-ceph",
"imageFeatures": "layering",
"imageFormat": "2",
"pool": "replicapool",
"storage.kubernetes.io/csiProvisionerIdentity": "1593101040137-8081-rook-ceph.rbd.csi.ceph.com"
},
"volumeHandle": "0001-0009-rook-ceph-0000000000000001-d11d2a4d-bd2e-11ea-b56e-7a7db811cab1"
},
"persistentVolumeReclaimPolicy": "Delete",
"storageClassName": "rook-ceph-block",
"volumeMode": "Filesystem"
},
"status": {
"phase": "Bound"
}
}
GET /services/:service_code/:environment_name/persistentvolumes/:id
Retrieve a persistent volume and all its info in a given environment.
| Attributes | |
|---|---|
id string |
The id of the persistent volume. This is the name of the resource. |
metadata object |
The metadata of the persistent volume. |
spec object |
The specification of the persistent volume. |
spec.accessModes string |
The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes). |
spec.capacity.storage string |
Storage capacity of the persistent volume. |
spec.persistentVolumeReclaimPolicy string |
One of Retain (manual reclamation), Recycle (basic scrub) or Delete (associated storage asset such as AWS EBS, GCE PD, Azure Disk, or OpenStack Cinder volume is deleted). |
spec.storageClassName string |
Storage class associated to the volume. |
spec.capacity.volumeMode string |
If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device. |
status.phase string |
Volume is in one of the following phases: Available, Bound, Released or Failed. |
Create a persistent volume
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumes"
Content-Type: application/json
{
"apiVersion": "v1",
"metadata": {
"name": "small-pvc",
"namespace": "default"
},
"spec": {
"accessModes": [
"ReadWriteOnce"
],
"resources": {
"requests": {
"storage": "10G"
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/persistentvolumes
Create a persistent volume in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the persistent volume. |
metadata object |
The metadata of the persistent volume. |
metadata.name string |
The name of the persistent volume. |
spec object |
The spec for the persistent volume. |
spec.accessModes array |
A list of access modes, the options are: ReadWriteOnce, ReadOnlyMany and ReadWriteMany. |
spec.capacity.storage string |
Measured in bytes. You can express storage as a plain integer or as a fixed-point integer using one of these suffixes: E, P, T, G, M, K. You can also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki. |
spec.<VOLUME_TYPE> object |
Volume types are identified by name and what volume types are supported differ heavily by Kubernetes deployment. The contents of the object also depend on the volume type. Examples of common volumes types are nfs, hostPath, or local. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the pod is created, if not specified will create the persistent volume in default. |
spec.storageClassName string |
Storage class associated to the volume. |
spec.claimRef array |
The name of the PersistentVolumeClaim associated to the persistent volume. |
spec.mountOptions array |
Mount options for when a Persistent Volume is mounted on a node. |
spec.nodeAffinity array |
Defines constraints that limit what nodes this volume can be accessed from. |
spec.persistentVolumeReclaimPolicy array |
One of Retain (manual reclamation), Recycle (basic scrub) or Delete (associated storage asset such as AWS EBS, GCE PD, Azure Disk, or OpenStack Cinder volume is deleted). |
spec.volumeMode array |
If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device. |
status.phase string |
Volume is in one of the following phases: Available, Bound, Released or Failed. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create persistent volume task. |
taskStatus string |
The status of the operation. |
Replace a persistent volume
curl -X PUT \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumes/my-persistent-volume"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "PersistentVolume",
"metadata": {
"annotations": {
"key": "value"
},
"name": "persistentvolumes-name"
},
"spec": {
"accessModes": [
"ReadWriteMany"
],
"capacity": {
"storage": "2Gi"
},
"claimRef": {
"apiVersion": "v1",
"kind": "PersistentVolumeClaim",
"name": "pv-claim-name",
"namespace": "default",
"resourceVersion": "259087",
"uid": "11957feb-1acc-4c7e-911e-f77d5d7be5ac"
},
"hostPath": {
"path": "/etc/path"
},
"persistentVolumeReclaimPolicy": "Retain",
"storageClassName": "standard",
"volumeMode": "Filesystem"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/persistentvolumes/:id
Replace a persistent volume in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the volume. |
metadata object |
The metadata of the volume. |
metadata.name string |
The name of the volume. |
specobject |
The specification used to replace and run the volume. |
spec.accessModesstring |
The desired access modes the volume should have. |
spec.capacity.storagestring |
The size of the claim. |
spec.hostPath.pathstring |
The path of the directory on the host. |
| Optional Attributes | |
|---|---|
metadata.annotations string |
Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. |
spec.claimRef string |
part of a bi-directional binding between PersistentVolume and PersistentVolumeClaim. Expected to be non-nil when bound. |
spec.persistentVolumeReclaimPolicy string |
What happens to a persistent volume when released from its claim. |
spec.storageClassName string |
Name of StorageClass to which this persistent volume belongs. Empty value means that this volume does not belong to any StorageClass. |
spec.volumeMode string |
Defines if a volume is intended to be used with a formatted filesystem or to remain in raw block state. Value of Filesystem is implied when not included in spec. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace volume task. |
taskStatus string |
The status of the operation. |
Delete a persistent volume
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumes/pvc-05097a93-120d-45d2"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/persistentvolumes/:id
Delete a perstent volume from a given environment.
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete persistent volume task. |
taskStatus string |
The status of the operation. |
Persistent Volume Claims
List persistent volume claims
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumeclaims"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "cmc-staging-mysql/cmc-stg",
"metadata": {
"annotations": {
"pv.kubernetes.io/bind-completed": "yes",
"pv.kubernetes.io/bound-by-controller": "yes",
"volume.beta.kubernetes.io/storage-provisioner": "rook-ceph.rbd.csi.ceph.com"
},
"creationTimestamp": "2020-04-27T12:01:22.000-04:00",
"finalizers": ["kubernetes.io/pvc-protection"],
"labels": {
"app": "cmc-staging-mysql",
"chart": "mysql-0.4.5",
"heritage": "Helm",
"release": "cmc-staging"
},
"name": "cmc-staging-mysql",
"namespace": "cmc-stg",
"resourceVersion": "111495311",
"selfLink": "/api/v2/namespaces/cmc-stg/persistentvolumeclaims/cmc-staging-mysql",
"uid": "ba115a65-e3c5-4e37-8548-e37ec395e79f"
},
"spec": {
"accessModes": ["ReadWriteOnce"],
"resources": {
"requests": {
"storage": "8Gi"
}
},
"storageClassName": "rook-ceph-block",
"volumeMode": "Filesystem",
"volumeName": "pvc-ba115a65-e3c5-4e37-8548-e37ec395e79f"
},
"status": {
"accessModes": ["ReadWriteOnce"],
"capacity": {
"storage": "8Gi"
},
"phase": "Bound"
}
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/persistentvolumeclaims
Retrieve a list of all persistent volume claims in a given environment.
| Attributes | |
|---|---|
id string |
The id of the persistent volume claim. This is the name and namespace of the resource. |
metadata object |
The metadata of the persistent volume claim. |
spec object |
The specification of the persistent volume claim. |
spec.accessModes string |
The requested access mode. The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes). |
spec.resources.requests.storage string |
The requested storage capacity of the persistent volume. |
spec.storageClassName string |
Storage class associated to the volume. |
spec.capacity.volumeMode string |
If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device. |
status object |
The status of the persistent volume claim. |
status.phase string |
The claim is in one of the following phases: Pending, Bound, Lost or Terminating. |
status.accessModes string |
The allocated access mode. The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes). |
status.capacity.storage string |
The allocated storage capacity. |
Get a persistent volume claim
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumeclaims/cmc-staging-mysql/cmc-stg"
The above command returns a JSON structured like this:
{
"data": {
"id": "cmc-staging-mysql/cmc-stg",
"apiVersion": "v1",
"kind": "PersistentVolumeClaim",
"metadata": {
"annotations": {
"pv.kubernetes.io/bind-completed": "yes",
"pv.kubernetes.io/bound-by-controller": "yes",
"volume.beta.kubernetes.io/storage-provisioner": "rook-ceph.rbd.csi.ceph.com"
},
"creationTimestamp": "2020-04-27T12:01:22.000-04:00",
"finalizers": ["kubernetes.io/pvc-protection"],
"labels": {
"app": "cmc-staging-mysql",
"chart": "mysql-0.4.5",
"heritage": "Helm",
"release": "cmc-staging"
},
"name": "cmc-staging-mysql",
"namespace": "cmc-stg",
"resourceVersion": "111495311",
"selfLink": "/api/v2/namespaces/cmc-stg/persistentvolumeclaims/cmc-staging-mysql",
"uid": "ba115a65-e3c5-4e37-8548-e37ec395e79f"
},
"spec": {
"accessModes": ["ReadWriteOnce"],
"resources": {
"requests": {
"storage": "8Gi"
}
},
"storageClassName": "rook-ceph-block",
"volumeMode": "Filesystem",
"volumeName": "pvc-ba115a65-e3c5-4e37-8548-e37ec395e79f"
},
"status": {
"accessModes": ["ReadWriteOnce"],
"capacity": {
"storage": "8Gi"
},
"phase": "Bound"
}
}
}
GET /services/:service_code/:environment_name/persistentvolumeclaims/:id
Retrieve a persistent volume claim and all its info in a given environment.
| Attributes | |
|---|---|
id string |
The id of the persistent volume claim. This is the name and namespace of the resource. |
metadata object |
The metadata of the persistent volume claim. |
spec object |
The specification of the persistent volume claim. |
spec.accessModes string |
The requested access mode. The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes). |
spec.resources.requests.storage string |
The requested storage capacity of the persistent volume. |
spec.storageClassName string |
Storage class associated to the volume. |
spec.capacity.volumeMode string |
If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device. |
status object |
The status of the persistent volume claim. |
status.phase string |
The claim is in one of the following phases: Pending, Bound, Lost or Terminating. |
status.accessModes string |
The allocated access mode. The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes). |
status.capacity.storage string |
The allocated storage capacity. |
Create a persistent volume claim
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumeclaims"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "PersistentVolumeClaim",
"metadata": {
"name": "small-pvc",
"namespace": "default"
},
"spec": {
"accessModes": [
"ReadWriteOnce"
],
"resources": {
"requests": {
"storage": "10G"
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/persistentvolumeclaims
Create a persistent volume claim in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the persistent volume claim. |
metadata object |
The metadata of the persistent volume claim. |
metadata.name string |
The name of the persistent volume claim. |
spec object |
The spec for the persistent volume claim. |
spec.accessModes array |
A list of access modes, the options are: ReadWriteOnce, ReadOnlyMany and ReadWriteMany. |
spec.resources.requests.storage string |
Measured in bytes. You can express storage as a plain integer or as a fixed-point integer using one of these suffixes: E, P, T, G, M, K. You can also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the pod is created, if not specified will create the claim in default. |
spec.storageClassName string |
The storage class for the persistent volume claim, will use the default if not specified. |
spec.resources.limits object |
Limits describe the maximum number of storage resources allowed. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create persistent volume claim task. |
taskStatus string |
The status of the operation. |
Replace a persistent volume claim
curl -X PUT \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumeclaims/my-persistent-volume-claim/default"
Content-Type: application/json
{
"id": "pv-claim-name/default",
"apiVersion": "v1",
"kind": "PersistentVolumeClaim",
"metadata": {
"name": "pv-claim-name",
"namespace": "default"
},
"spec": {
"accessModes": [
"ReadWriteOnce"
],
"resources": {
"requests": {
"storage": "1Gi"
}
},
"storageClassName": "standard",
"volumeName": "persistentvolumes-name",
"dataSource": "dataSource"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/persistentvolumeclaims/:id
Replace a persistent volume claim in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the claim. |
metadata object |
The metadata of the claim. |
metadata.name string |
The name of the claim. |
specobject |
The specification used to replace and run the claim. |
spec.accessModesstring |
The desired access modes the volume should have. |
spec.resources.requests.storagestring |
The size of the claim. |
spec.storageClassNamestring |
The name of the StorageClass required by the claim. |
spec.volumeNamestring |
The binding reference to the PersistentVolume backing this claim. Only required if claim is bound. |
| Optional Attributes | |
|---|---|
spec.volumemode string |
What type of volume is required by the claim. Value of Filesystem is implied when not included in claim spec. |
spec.dataSource string |
This field can be used to specify either: an existing VolumeSnapshot object, an existing PVC or an existing custom resource/object that implements data population. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace persistent volume claim task. |
taskStatus string |
The status of the operation. |
Delete a persistent volume claim
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumeclaims/cmc-staging-mysql/cmc-stg"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/persistentvolumeclaims/:id
Delete a perstent volume claim from a given environment.
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete persistent volume claim task. |
taskStatus string |
The status of the operation. |
Access control
Service accounts
List service accounts
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/serviceaccounts"
The above command returns a JSON structured like this:
{
"metadata": {
"name": "vpnkit-controller",
"namespace": "kube-system",
"selfLink": "/api/v2/namespaces/kube-system/serviceaccounts/vpnkit-controller",
"uid": "b9afa8a8-3d64-4605-959f-12bb5c6cfba2",
"resourceVersion": "481",
"creationTimestamp": "2020-09-18T14:47:48Z",
"annotations": {
"kubectl.kubernetes.io/last-applied-configuration": "{\"apiVersion\":\"v1\",\"kind\":\"ServiceAccount\",\"metadata\":{\"annotations\":{},\"name\":\"vpnkit-controller\",\"namespace\":\"kube-system\"}}\n"
}
},
"secrets": [
{
"name": "vpnkit-controller-token-hl674"
}
]
}
]
}
GET /services/:service_code/:environment_name/serviceaccounts
Retrieve a list of all service accounts in a given environment.
| Attributes | |
|---|---|
id string |
The id of the service account. |
metadata.annotations map |
The annotations of the service account. |
metadata object |
The metadata of the service account. |
metadata.creationTimestamp string |
The date of creation of the service account as a string. |
metadata.name string |
The name of the service account. |
metadata.namespace string |
The namespace in which the service account is created. |
metadata.uid object |
The UUID of the service account. |
metadata.secrets List<object> |
The secrets of the service account. |
secretsSize integer |
The number of secrets of the service account. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a service account
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/serviceaccounts/serviceaccount-name/serviceaccount-namespace"
The above command returns a JSON structured like this:
{
"data": {
"id": "default",
"age": "1w5d",
"secretsSize": 1,
"metadata": {
"creationTimestamp": "2020-09-18T10:46:40.000-04:00",
"name": "default",
"namespace": "default",
"uid": "80a0de4d-a187-44c3-b691-1481220a5817"
},
"secrets": [
{
"name": "default-token-lrth9"
}
]
},
"fieldTransitions": {},
"operations": []
}
GET /services/:service_code/:environment_name/serviceaccounts/:id
Retrieve a service account and all its info in a given environment.
| Attributes | |
|---|---|
id string |
The id of the service account. |
metadata object |
The metadata of the service account. |
metadata.creationTimestamp string |
The date of creation of the service account as a string. |
metadata.name string |
The name of the service account. |
metadata.namespace string |
The namespace in which the service account is created. |
metadata.uid object |
The UUID of the service account. |
metadata.secrets List<object> |
The secrets of the service account. |
secretsSize integer |
The number of secrets of the service account. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a service account
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/serviceaccounts"
Content-Type: application/json
{
"apiVersion": "v1",
"metadata": {
"name": "service-account-name",
"namespace": "default"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/serviceaccounts
Create a service account in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the service account. |
metadata object |
The metadata of the service account. |
metadata.name string |
The name of the service account. |
metadata.namespace string |
The namespace of the service account. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create service account task. |
taskStatus string |
The status of the operation. |
Replace a service account
curl -X PUT \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/serviceaccounts/service-account-name/namespace-name"
Content-Type: application/json
{
"metadata": {
"name": "service-account-name",
"namespace": "namespace-name"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/serviceaccounts/:id
Replace a service account in a given environment.
| Required Attributes | |
|---|---|
metadata object |
The metadata of the service account. |
metadata.name string |
The name of the service account. |
metadata.namespace string |
The namespace of the service account. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create service account task. |
taskStatus string |
The status of the operation. |
Delete a service account
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/serviceaccounts/my-service-account/my-namespace"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/serviceaccounts/:id
Delete a service account from a given environment.
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete service account task. |
taskStatus string |
The status of the operation. |
Roles
List (namespace) Roles
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/roles"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "role-id",
"age": "1w4d",
"metadata": {
"creationTimestamp": "2020-09-18T10:01:26.000-04:00",
"name": "kubeadm:bootstrap-signer-clusterinfo",
"namespace": "kube-public",
"uid": "57ef0321-e44a-43c9-9f2a-e448c3a66a46"
},
"rules": [
{
"apiGroups": [],
"resourceNames": [],
"resources": [],
"verbs": []
}
]
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/roles
Retrieve a list of all roles in a given environment.
| Attributes | |
|---|---|
id string |
The id of the role. |
metadata object |
The metadata of the role. |
metadata.creationTimestamp string |
The date of creation of the service account as a string. |
metadata.name string |
The name of the role. |
metadata.namespace string |
The namespace in which the role is created. |
metadata.uid object |
The UUID of the role. |
rules array |
The array of rules associated with this role. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a role
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/roles/role-name/role-namespace"
The above command returns a JSON structured like this:
{
"data": {
"id": "kubeadm:bootstrap-signer-clusterinfo",
"age": "1w4d",
"apiVersion": "rbac.authorization.k8s.io/v1",
"kind": "Role",
"metadata": {
"creationTimestamp": "2020-09-18T10:01:26.000-04:00",
"name": "kubeadm:bootstrap-signer-clusterinfo",
"namespace": "kube-public",
"uid": "57ef0321-e44a-43c9-9f2a-e448c3a66a47"
},
"rules": [
{
"apiGroups": [],
"resourceNames": [],
"resources": [],
"verbs": []
}
]
}
}
GET /services/:service_code/:environment_name/roles/:id
Retrieve a role and all its info in a given environment.
| Attributes | |
|---|---|
id string |
The id of the role. |
apiVersion string |
The API version used to retrieve this role. |
metadata object |
The metadata of the role. |
rules array |
The array of rules associated with this role. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a role
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/roles"
Content-Type: application/json
{
"apiVersion": "rbac.authorization.k8s.io/v1",
"kind": "Role",
"namespace": "default",
"name": "test-name",
"metadata": {
"namespace": "default",
"name": "test-name"
},
"rules": [
{
"apiGroups": [
""
],
"resources": [
"resource"
],
"verbs": [
"get",
"watch"
]
}
]
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/roles
Create a role in a given environment.
| Attributes | |
|---|---|
id string |
The id of the role. |
apiVersion string |
The API version used to create this role. |
metadata.name string |
The name of the role. |
metadata.namespace string |
The namespace of the role. |
rules array |
The array of rules associated with this role. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create role task. |
taskStatus string |
The status of the operation. |
Replace a role
curl -X PUT \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/roles/role-name/namespace-name?cluster_id=:cluster_id"
Content-Type: application/json
{
"metadata": {
"name": "role-name",
"namespace": "namespace-name"
}
"rules": [
{
"apiGroups": [
""
],
"resources": [
"resource"
],
"verbs": [
"get",
"watch",
"..."
]
}
]
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/roles/:id?cluster_id=:cluster_id
Replace a role in a given environment.
| Required Attributes | |
|---|---|
metadata object |
The metadata of the role. |
metadata.name string |
The name of the role. |
metadata.namespace string |
The namespace of the role. |
metadata.namespace string |
The namespace of the role. |
| Optional Attributes | |
|---|---|
rules array |
The array of rules associated with this role. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace role operation. |
taskStatus string |
The status of the operation. |
Delete a role
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/roles/default-token-xxxmt/default"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/roles/:id
Delete a roles from a given environment.
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete role task. |
taskStatus string |
The status of the operation. |
Role bindings
List role bindings
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/rolebindings"
The above command returns a JSON structured like this:
{
"data": {
"entity": {
"id": "kubeadm:bootstrap-signer-clusterinfo",
"age": "1w5d",
"metadata": {
"creationTimestamp": "2020-09-18T10:46:32.000-04:00",
"name": "kubeadm:bootstrap-signer-clusterinfo",
"namespace": "kube-public",
"uid": "4fcfe5b9-a1c3-4b3b-9cb6-6df4a1da945f"
},
"roleRef": {
"apiGroup": "rbac.authorization.k8s.io",
"kind": "Role",
"name": "kubeadm:bootstrap-signer-clusterinfo"
},
"subjects": [
{
"apiGroup": "rbac.authorization.k8s.io",
"kind": "User",
"name": "system:anonymous"
}
]
},
"fieldTransitions": {},
"operations": []
},
}
GET /services/:service_code/:environment_name/rolebindings
Retrieve a list of all role bindings in a given environment.
| Attributes | |
|---|---|
id string |
The id of the role binding. |
metadata object |
The metadata of the role binding. |
metadata.creationTimestamp string |
The date of creation of the role binding as a string. |
metadata.name string |
The name of the role binding. |
metadata.namespace string |
The namespace in which the role binding is created. |
metadata.uid object |
The UUID of the role binding. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a role binding
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/rolebindings/rolebinding-name/rolebinding-namespace"
The above command returns a JSON structured like this:
{
"data": {
"id": "kubeadm:bootstrap-signer-clusterinfo",
"age": "1w5d",
"metadata": {
"creationTimestamp": "2020-09-18T10:46:32.000-04:00",
"name": "kubeadm:bootstrap-signer-clusterinfo",
"namespace": "kube-public",
"uid": "4fcfe5b9-a1c3-4b3b-9cb6-6df4a1da945f"
},
"roleRef": {
"apiGroup": "rbac.authorization.k8s.io",
"kind": "Role",
"name": "kubeadm:bootstrap-signer-clusterinfo"
},
"subjects": [
{
"apiGroup": "rbac.authorization.k8s.io",
"kind": "User",
"name": "system:anonymous"
}
]
},
"fieldTransitions": {},
"operations": []
},
}
GET /services/:service_code/:environment_name/rolebindings/:id
Retrieve a role binding and all its info in a given environment.
| Attributes | |
|---|---|
id string |
The id of the role binding. |
apiVersion string |
The API version used to retrieve this role binding. |
metadata object |
The metadata of the role binding. |
subjects array |
The array of subjects associated with this role binding. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a role binding
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/rolebindings"
Content-Type: application/json
{
"kind": "Rolebinding",
"metadata": {
"name": "rolebinding-name",
"namespace": "namespace-name"
},
"roleRef": {
"apiGroup": "rbac.authorization.k8s.io",
"kind": "Role",
"name": "role-name"
},
"subjects": [
{
"kind": "ServiceAccount",
"name": "service-account-name",
"namespace": "service-account-namespace"
},
{
"kind": "Group",
"name": "group-name",
"namespace": "group-namespace"
},
{
"kind": "User",
"name": "user-name",
}
]
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/rolebindings
Create a role binding in a given environment.
| Required Attributes | |
|---|---|
metadata object |
The metadata of the role binding. |
metadata.name string |
The name of the role binding. |
metadata.namespace string |
The namespace of the role binding. |
roleRefobject |
The role to bind. Can reference a Role in the current namespace or a ClusterRole in the global namespace. |
subjectsarray |
Subjects hold references to the objets the role applies to. Can be users, groups, or service accounts. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create role binding task. |
taskStatus string |
The status of the operation. |
Replace a role binding
curl -X PUT \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/rolebindings/rolebinding-name/namespace-name"
Content-Type: application/json
{
"metadata": {
"name": "service-account-name",
"namespace": "namespace-name"
},
"roleRef": {
"apiGroup": "",
"kind": "Role",
"name": "role-name"
},
"subjects": [
{
"kind": "ServiceAccount",
"name": "default",
"namespace": "default"
},
{
"kind": "user",
"name": "user1",
}
]
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/rolebindings/:id
Replace a role binding in a given environment.
| Required Attributes | |
|---|---|
metadata object |
The metadata of the role binding. |
metadata.name string |
The name of the role binding. |
metadata.namespace string |
The namespace of the role binding. |
roleRefobject |
The role to bind. Can reference a Role in the current namespace or a ClusterRole in the global namespace. |
subjectsarray |
Subjects hold references to the objets the role applies to. Can be users, groups, or service accounts. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace role binding operation. |
taskStatus string |
The status of the operation. |
Delete a role binding
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/rolebindings/default-token-xxxmt/default"
The above command returns a JSON structured like this:
json { "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b", "taskStatus": "PENDING" }DELETE /services/:service_code/:environment_name/rolebindings/:id
Delete a role binding from a given environment.
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete role binding task. |
taskStatus string |
The status of the operation. |
Releases
List releases
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/releases"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "my-namespace/my-cloudflare",
"name": "my-cloudflare",
"info": {
"first_deployed": "2020-11-03T09:48:49.301166-05:00",
"last_deployed": "2020-11-05T11:24:37.096888-05:00",
"deleted": "",
"description": "Upgrade complete",
"status": "installed",
"notes": "You can connect to the container running cloudflare-dyndns. To open a shell session in the pod run the following:\n..."
},
"chart": {
"metadata": {
"name": "cloudflare-dyndns",
"home": "https://github.com/billimek/billimek-charts/tree/master/charts/cloudflare-dyndns",
"sources": [
"https://github.com/hotio/docker-cloudflare-ddns/",
"https://github.com/billimek/billimek-charts"
],
"version": "2.0.0",
"description": "Dynamic DNS using Cloudflare's DNS Services",
"keywords": [
"cloudflare",
"dynamicdns"
],
"maintainers": [
{
"name": "billimek",
"email": "jeff@billimek.com"
}
],
"icon": "https://www.cloudflare.com/img/cf-facebook-card.png",
"apiVersion": "v1",
"appVersion": "1.0",
"deprecated": false
},
"values": {
"affinity": {},
"cloudflare": {
"detection_mode": "dig-google.com",
"hosts": "somehosts",
"log_level": 1.0,
"record_types": "somerecordtypes",
"sleep_interval": 300.0,
"token": "sometoken",
"user": "someuser",
"zones": "somezones"
},
"image": {
"pullPolicy": "Always",
"repository": "hotio/cloudflare-ddns",
"tag": "latest"
},
"nodeSelector": {},
"replicaCount": 1.0,
"resources": {},
"tolerations": []
}
},
"config": {
"affinity": {},
"cloudflare": {
"detection_mode": "dig-google.com",
"hosts": "somehosts",
"log_level": 1.0,
"record_types": "somerecordtypes",
"sleep_interval": 300.0,
"token": "sometoken",
"user": "someuser",
"zones": "somezones"
},
"image": {
"pullPolicy": "Always",
"repository": "hotio/cloudflare-ddns",
"tag": "latest"
},
"nodeSelector": {},
"replicaCount": 1.0,
"resources": {},
"tolerations": []
},
"version": 10,
"namespace": "my-namespace",
"keepHistory": false,
"chartVersion": "cloudflare-dyndns / 2.0.0"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/releases
Or
GET /services/:service_code/:environment_name/releases?namespace=default
Retrieve a list of all releases in a given environment.
| Optional | |
|---|---|
namespace string |
The namespace to list the release. This needs the exact value. |
| Attributes | |
|---|---|
id string |
The release id, of the form namespace/releaseName. |
name string |
The name of the release. |
info object |
The information about the release. |
info.first_deployed string |
The annotations of the pod. |
info.last_deployed string |
The date of creation of the pod as a string. |
info.deleted string |
The labels associated to the pod. |
info.description string |
The name of the pod. |
info.status string |
The status of the release. Possible values are unknown, installed, uninstalled, superseded, failed, uninstalling, pending-install, pending-upgrade, pending-rollback. |
info.notes string |
The notes linked to the release. |
chartobject |
The information related to the chart of used in the release. |
chart.version string |
The version of the chart. |
chart.metadata object |
The metadata associated to the chart. |
chart.metadata.name string |
The name of the chart. |
chart.metadata.home string |
The home URL for the chart. |
chart.metadata.sources list |
The list of source of the charts. |
chart.metadata.version string |
The version of the chart. |
chart.metadata.description string |
The description of the chart. |
chart.metadata.keywords list |
The list of keywords linked to the chart. |
chart.metadata.maintainers list |
The list of the maintainer contact information. |
chart.metadata.icon string |
The icon URL for the chart. |
chart.metadata.appVersion string |
The version of the application. |
chart.metadata.deprecate bool |
If the chart is deprecated or not of the application. |
config object |
All values that were used to install the release. |
versionstring |
The revision of the release. |
namespacestring |
The namespace to which the release is installed. |
The information is not totally returned in the list. We filter out the manifest portion. We also filter out the files and the templates of the chart details. This information will be present in the GET request for an individual release.
Get release
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/releases/my-namespace/my-cloudflare"
The above command returns a JSON structured like this:
{
"data": {
"id": "my-namespace/my-cloudflare",
"name": "my-cloudflare",
"info": {
"first_deployed": "2020-11-03T09:48:49.301166-05:00",
"last_deployed": "2020-11-05T19:44:46.775668959Z",
"deleted": "",
"description": "Upgrade complete",
"status": "installed",
"notes": "You can connect to the container running cloudflare-dyndns. To open a shell session in the pod run the following:\n..."
},
"chart": {
"metadata": {
"name": "cloudflare-dyndns",
"home": "https://github.com/billimek/billimek-charts/tree/master/charts/cloudflare-dyndns",
"sources": [
"https://github.com/hotio/docker-cloudflare-ddns/",
"https://github.com/billimek/billimek-charts"
],
"version": "2.0.0",
"description": "Dynamic DNS using Cloudflare's DNS Services",
"keywords": [
"cloudflare",
"dynamicdns"
],
"maintainers": [
{
"name": "billimek",
"email": "jeff@billimek.com"
}
],
"icon": "https://www.cloudflare.com/img/cf-facebook-card.png",
"apiVersion": "v1",
"appVersion": "1.0",
"deprecated": false
},
"templates": [
{
"name": "templates/NOTES.txt",
"data": "WW91I...fScp"
},
{
"name": "templates/_helpers.tpl",
"data": "e3svKi...9Cg=="
},
{
"name": "templates/deployment.yaml",
"data": "YXBpVm...9Cg=="
},
{
"name": "templates/secret.yaml",
"data": "YXBpVmVy...X0="
}
],
"values": {
"affinity": {},
"cloudflare": {
"detection_mode": "dig-google.com",
"hosts": "somehosts",
"log_level": 1.0,
"record_types": "somerecordtypes",
"sleep_interval": 300.0,
"token": "sometoken",
"user": "someuser",
"zones": "somezones"
},
"image": {
"pullPolicy": "Always",
"repository": "hotio/cloudflare-ddns",
"tag": "latest"
},
"nodeSelector": {},
"replicaCount": 1.0,
"resources": {},
"tolerations": []
},
"files": [
{
"name": ".helmignore",
"data": "IyBQYX...b2oK"
},
{
"name": "README.md",
"data": "IyBE..4K"
}
]
},
"manifest": "---\n# Source: cloudflare-dyndns/templates/secret.yaml\napiVersion: v1\n...",
"config": {
"affinity": {},
"cloudflare": {
"detection_mode": "dig-google.com",
"hosts": "somehosts",
"log_level": 1.0,
"record_types": "somerecordtypes",
"sleep_interval": 300.0,
"token": "sometoken",
"user": "someuser",
"zones": "somezones"
},
"image": {
"pullPolicy": "Always",
"repository": "hotio/cloudflare-ddns",
"tag": "latest"
},
"nodeSelector": {},
"replicaCount": 1.0,
"resources": {},
"tolerations": []
},
"version": 11,
"namespace": "my-namespace",
"keepHistory": false,
"chartVersion": "cloudflare-dyndns / 2.0.0"
}
}
GET /services/:service_code/:environment_name/releases/:id
| Attributes | |
|---|---|
id string |
The release id, of the form namespace/releaseName. |
name string |
The name of the release. |
info object |
The information about the release. |
info.first_deployed string |
The date the release was created. |
info.last_deployed string |
The date the release was last updated. |
info.deleted string |
The labels associated to the pod |
info.description string |
Description of the release's status. |
info.status string |
The status of the release. Possible values are unknown, installed, uninstalled, superseded, failed, uninstalling, pending-install, pending-upgrade, pending-rollback. |
info.notes string |
The notes linked to the release. |
chartobject |
The information related to the chart used to install the release. |
chart.version string |
The version of the chart. |
chart.metadata object |
The metadata associated to the chart. |
chart.metadata.name string |
The name of the chart. |
chart.metadata.home string |
The home URL for the chart. |
chart.metadata.sources list |
The list of source of the charts. |
chart.metadata.version string |
The version of the chart. |
chart.metadata.description string |
The description of the chart. |
chart.metadata.keywords list |
The list of keywords linked to the chart. |
chart.metadata.maintainers list |
The list of the maintainer contact information. |
chart.metadata.icon string |
The icon URL for the chart. |
chart.metadata.appVersion string |
The version of the application. |
chart.metadata.deprecate bool |
If the chart is deprecated or not of the application. |
chart.templates list |
The list of templates contained inside the chart. |
chart.templates.name string |
The path name of the template inside the chart. |
chart.templates.data string |
The contents of the template. This is a base64 encoded string. |
chart.files list |
The list of files contained inside the chart. These are not YAML files unlike the templates. |
chart.files.name string |
The path name of the file inside the chart. |
chart.files.data string |
The contents of the file. This is a base64 encoded string. |
manifest string |
The YAML Kubernetes resources created by the Helm templating. |
config object |
All values that were used to install the release. |
versionstring |
The revision of the release. |
namespacestring |
The namespace to which the release is installed. |
Rollback release to previous revision
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/releases/pspensieri/aerospike-1579797954&operation=rollback"
The above command returns a JSON structured like this:
{
"data": {
"name": "aerospike-1579797954",
"version": 8,
"info": {
"deleted": "",
"description": "Rollback to 6",
"status": "deployed",
...
...
},
"taskId": "13943961-4a2c-4439-b7c9-05113d3b593a",
"taskStatus": "SUCCESS"
}
POST /services/:service_code/:environment_name/releases/:id?operation=rollback
Rollback a release in a given environment to the previous revision.
| Attributes | |
|---|---|
data Object |
The release object. See get release for a description of the release attributes. |
taskId string |
The task id related to the pod rollback. |
taskStatus string |
The status of the operation. |
Upgrade release
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/releases/my-namespace/my-aerospike?operation=upgrade"
-d "request_body"
Request body examples:
// Change to the latest version of a chart
{
"upgradeChart": {
"name": "aerospike",
"repository": {
"url": "https://aerospike.github.io/aerospike-kubernetes-enterprise"
}
}
}
// Change to a specific version of a chart
{
"upgradeChart": {
"name": "aerospike",
"version": "4.9.0",
"repository": {
"url": "https://aerospike.github.io/aerospike-kubernetes-enterprise"
}
}
}
// Change the values for the latest version
{
"upgradeChart": {
"name": "aerospike",
"repository": {
"url": "https://aerospike.github.io/aerospike-kubernetes-enterprise"
}
},
"upgradeValues": "\"replicaCount\": 3"
}
The above commands return JSON structured like this:
{
"taskId": "c50390c7-9d5b-4af4-a2da-e2a2678a83e8",
"taskStatus": "SUCCESS"
}
POST /services/:service_code/:environment_name/releases/:id?operation=upgrade
Upgrade a release in a given environment.
| Required | |
|---|---|
upgradeChart Object |
The chart object that should be used to ugprade the release. |
upgradeChart.name string |
The chart name. |
repository Object |
The repository object to which the chart belongs. |
repository.url string |
The repository's URL. |
| Optional | |
|---|---|
upgradeChart.version string |
The chart version that should be used to upgrade the chart. If none is provided, the latest is used. |
upgradeChart.values string |
YAML structured text that will overwrite the default values for the upgrade/installation of the chart. |
| Attributes | |
|---|---|
taskId string |
The task id related to the pod upgrade. |
taskStatus string |
The status of the operation. |
Uninstall a release
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/releases/pspensieri/aerospike-1579797954&operation=uninstall"
-d "request_body"
Request body example:
{
"keepHistory": true
}
The above command returns a JSON structured like this:
{
"data": {
"version": 0,
"keepHistory": false
},
"taskId": "938f11b2-b37d-459e-8cf2-dea05c4d8f63",
"taskStatus": "SUCCESS"
}
POST /services/:service_code/:environment_name/releases/:id?operation=uninstall
Uninstall a release in a given environment.
| Optional | |
|---|---|
keepHistory bool |
If true, will keep release history after uninstalling. Defaults to false. |
| Attributes | |
|---|---|
version string |
The uninstalled release's revision. Revision 0 indicated it was uninstalled. |
keepHistory string |
The keepHistory value used when uninstalling the chart. |
taskId string |
The task id related to the pod uninstall. |
taskStatus string |
The status of the operation. |
Charts
List charts
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/charts"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "helm-stable/aerospike",
"name": "aerospike",
"description": "A Helm chart for Aerospike in Kubernetes",
"version": "0.3.3",
"license": "",
"deprecated": false,
"repository": {
"url": "https://kubernetes-charts.storage.googleapis.com",
"name": "helm-stable",
"kind": 0,
"official": false,
"displayName": "Stable",
"repositoryId": "3cc327ae-9403-4521-9b71-f9a41d5f86c8",
"organizationName": "helm",
"verifiedPublisher": false,
"organizationDisplayName": "Helm"
},
"packageId": "c4b6ad70-898d-4093-bec8-089d5f48daeb",
"displayName": "",
"normalizedName": "aerospike",
"appVersion": "v4.5.0.5",
"logoImageId": "50bcf132-ff98-4f9a-9e6a-0c0b06649e48",
"logoImageUrl": "https://artifacthub.io/image/50bcf132-ff98-4f9a-9e6a-0c0b06649e48"
}
],
"metadata": {
"pageSize": 50,
"pageCurrent": 1,
"recordCount": 148
}
}
GET /services/:service_code/:environment_name/charts
Retrieve a list of all charts in a given environment. To get more chart details, such as available versions, the chart's readme and list of maintainers, see the GET request for an individual chart.
| Attributes | |
|---|---|
id string |
The id for the chart, of the form repositoryName/chartName. |
name string |
The chart name. |
description string |
The chart description. |
version string |
The latest chart version. |
license string |
The chart's license. |
deprecated boolean |
True if the chart is deprecated. |
repository object |
The chart's parent repository. |
repoository.url string |
The repository URL. |
repository.name string |
The repository name. |
repository.kind integer |
The repository kind, where {0: Helm chart, 1: Falco rule, 2: OPA policy, 3: OLM operator }. |
repository.official boolean |
True if it is an official repository. That is, if the publisher owns the software deployed by the package. |
repository.displayName string |
The repository's display name. |
repository.repositoryId UUID |
The UUID of the repository. |
repository.organizationName string |
The name of the organization that owns the repository. |
repository.organizationDisplayName string |
The display name of the organization that owns the repository. |
repository.verifiedPublisher boolean |
True if the publisher owns the repository. |
packageId UUID |
The UUID of the package, given by ArtifactHub. |
displayName string |
The chart's display name. |
normalizedName string |
The chart's normalized name. |
appVersion string |
The chart's app version. |
logoImageId UUID |
The UUID of the package's logo, given by ArtifactHub. |
logoImageUrl string |
The URL for the chart's logo. |
Get chart
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/charts/k8s-at-home/cloudflare-dyndns"
The above command returns a JSON structured like this:
{
"data": {
"keywords": [
"cloudflare",
"dynamicdns"
],
"maintainers": [
{
"name": "billimek",
"email": "jeff@billimek.com"
}
],
"links": [
{
"url": "https://github.com/hotio/docker-cloudflare-ddns/",
"name": "source"
},
{
"url": "https://github.com/billimek/billimek-charts",
"name": "source"
}
],
"homeUrl": "https://github.com/billimek/billimek-charts/tree/master/charts/cloudflare-dyndns",
"availableVersions": [
{
"version": "1.0.0",
"createdAt": 1576998322
},
{
"version": "2.0.0",
"createdAt": 1578688072
}
],
"readMe": "# Dynamic DNS using Cloudflare's DNS Services\n...",
"id": "k8s-at-home/cloudflare-dyndns",
"name": "cloudflare-dyndns",
"description": "Dynamic DNS using Cloudflare's DNS Services",
"version": "2.0.0",
"license": "",
"deprecated": false,
"repository": {
"url": "https://k8s-at-home.com/charts/",
"name": "k8s-at-home",
"kind": 0,
"official": false,
"displayName": "charts",
"repositoryId": "9b40a3b3-ed2a-405f-8919-3b824d4f661d",
"organizationName": "k8s-at-home",
"verifiedPublisher": true,
"organizationDisplayName": "k8s@home"
},
"packageId": "a6cd6148-977a-4852-8761-80234f39d90b",
"displayName": "",
"normalizedName": "cloudflare-dyndns",
"appVersion": "1.0",
"logoImageId": "3a0eac41-21b4-4a1b-b127-c7e70123eda8",
"logoImageUrl": "https://artifacthub.io/image/3a0eac41-21b4-4a1b-b127-c7e70123eda8"
}
}
GET /services/:service_code/:environment_name/charts/:id
Retrieve a specific chart in a given environment.
| Attributes | |
|---|---|
id string |
The id for the chart, of the form repositoryName/chartName. |
name string |
The chart name. |
description string |
The chart description. |
version string |
The latest chart version. |
license string |
The chart's license. |
deprecated boolean |
True if the chart is deprecated. |
repository object |
The chart's parent repository. |
repoository.url string |
The repository URL. |
repository.name string |
The repository name. |
repository.kind integer |
The repository kind, where {0: Helm chart, 1: Falco rule, 2: OPA policy, 3: OLM operator }. |
repository.official boolean |
True if it is an official repository. That is, if the publisher owns the software deployed by the package. |
repository.displayName string |
The repository's display name. |
repository.repositoryId UUID |
The UUID of the repository. |
repository.organizationName string |
The name of the organization that owns the repository. |
repository.organizationDisplayName string |
The display name of the organization that owns the repository. |
repository.verifiedPublisher boolean |
True if the publisher owns the repository. |
packageId UUID |
The UUID of the package, given by ArtifactHub. |
displayName string |
The chart's display name. |
normalizedName string |
The chart's normalized name. |
appVersion string |
The chart's app version. |
logoImageId UUID |
The UUID of the package's logo, given by ArtifactHub. |
logoImageUrl string |
The URL for the chart's logo. |
keywords Array[string] |
The chart's keywords. |
maintainers Array[Object] |
The names and emails of chart maintainers. |
homeUrl Array[Object] |
The chart's home URL. |
availableVersions Array[Object] |
The available chart versions and their created dates. |
Install chart
curl --request POST \
--url https://cloudmc_endpoint/api/v2/services/a_service/an_environment/charts \
--header 'MC-Api-Key: your_api_key' \
--data '{
"namespace": "my-namespace",
"releaseName": "my-aerospike",
"name": "aerospike",
"version": "5.0.0",
"values": ""
"repository": {
"url": "https://aerospike.github.io/aerospike-kubernetes-enterprise"
}
}'
The above command returns a JSON structured like this:
{
"taskId": "ef70cafa-0544-4709-a66a-c68595ee105a",
"taskStatus": "SUCCESS"
}
POST /services/:service_code/:environment_name/charts
Install a chart in a given environment.
| Required | |
|---|---|
namespace string |
The namespace in which the chart will be installed. |
releaseName string |
The desired release name. |
name string |
The chart name. |
repository object |
The chart's parent repository from which it should be installed. |
repoository.url string |
The repository URL. |
| Optional | |
|---|---|
version string |
The chart version to be installed. Defaults to the latest version if left blank. |
values string |
The values used to install the chart. Must be a valid Yaml format. If not provided, the chart's default values will be used. |
insecureServerboolean |
True if accessing the chart requires an unsecured connection. |
Azure plugin
The Azure plugin provides endpoints for carrying out operations on CloudMC compute and networking entities. It also enforces CloudMC's environment-centric multi-tenancy model and RBAC over top of Azure.
Compute
Instances
Deploy and manage your instances.
List instances
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/azure/example/instances"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Compute/virtualMachines/example-small-server",
"name": "example-small-server",
"machineType": "Standard_B1ls",
"numberOfCores": 2,
"memoryInGB": 1.75,
"imagePublisher": "LinuxPublisher",
"imageOffer": "CoreOS",
"imageSku": "Alpha",
"imageVersion": "1000.0.0",
"osType": "Linux",
"displayImage": "CoreOS - Alpha",
"region": "canadacentral",
"privateIp": "10.0.0.4",
"macAddress": "00-0D-3A-84-0B-EF",
"subnetName": "default",
"networkName": "vn_root_qyg",
"supportsPremiumIO": true,
"supportsUltraIO": false,
"attachableDiskSlots": 2,
"usedLuns": [1],
"powerState": "PowerState/running",
"displayPowerState": "running",
"networkInterfaces": [
{
"id": "/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/networkInterfaces/nicexample",
"name": "nicexample",
"primary": true
}
],
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/instances
Retrieve a list of all instances in a given environment.
| Attributes | |
|---|---|
id string |
The id of the instance. This is a canonized id from azure which is the form of /subscriptions/:subscriptionid/resourceGroups/:resourcegroup/providers/Microsoft.Compute/virtualMachines/:instanceName. |
name string |
The name of the instance. |
machineTypestring |
The type of machine assigned for this instance. |
numberOfCoresint |
The number of cores provisioned for this instance. This is determined by the machine type. |
memoryInGBint |
The number of memory in GB provisioned for this instance. This is determined by the machine type. |
imagePublisherstring |
The publisher of the instance used to create the instance. |
imageOfferstring |
The image offer that was used to create the instance. |
imageSkustring |
The image SKU that was used to create the instance. |
imageVersionstring |
The image version that was used to create the instance. |
displayImagestring |
Displayable value of the image information. |
osTypestring |
The OS type of the instance. This can be either Windows or Linux. |
regionstring |
The region in which the instance is located. |
privateIpstring |
The private ip address assigned to the instance. |
internalFqdnstring |
The internal FQDN assigned to the instance. |
macAddressstring |
The MAC address assigned to the instance. |
subnetNamestring |
The name of the subnet that the instance is part of. |
networkNamestring |
The name of the network that the instance is part of. |
supportsPremiumIOboolean |
If the instance supports Premium disks. This is fixed by the machine type. |
supportsUltraIOboolean |
If the instance supports Ultra disks. This is fixed by the machine type. |
attachableDiskSlotsinteger |
The number of managed disks that can be attached to the instance. This is fixed by the machine type. |
usedLunsarray |
An array of all the LUNs associated with the managed disks attached to this instance. |
publicIpstring |
The public ip address assigned to the instance. |
powerStatestring |
The status of the instance. One of the following values: PowerState/running, PowerState/deallocating, PowerState/deallocated, PowerState/starting, PowerState/stopped, PowerState/stopping and PowerState/unknown. |
displayPowerStatestring |
The status of the instance. One of the following values: running, deallocating, deallocated, starting, stopped, stopping and unknown. |
networkInterfaceslist |
A list of network interfaces of the instance. Contains fields: id, name, primary. |
Retrieve an instance
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/azure/example/instances/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Compute/virtualMachines/example-small-server"
The above command returns a JSON structured like this:
{
"data": {
"id": "/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Compute/virtualMachines/example-small-server",
"name": "example-small-server",
"machineType": "Standard_B1s",
"numberOfCores": 2,
"memoryInGB": 1.75,
"imagePublisher": "LinuxPublisher",
"imageOffer": "CoreOS",
"imageSku": "Alpha",
"imageVersion": "1000.0.0",
"osType": "Linux",
"displayImage": "CoreOS - Alpha",
"region": "canadacentral",
"privateIp": "10.0.0.4",
"macAddress": "00-0D-3A-0B-F2-96",
"subnetName": "default",
"networkName": "vn_root_qyg",
"supportsPremiumIO": true,
"supportsUltraIO": false,
"attachableDiskSlots": 2,
"usedLuns": [],
"powerState": "PowerState/running",
"displayPowerState": "running",
"networkInterfaces": [
{
"id": "/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/networkInterfaces/nicexample",
"name": "nicexample",
"primary": true
}
],
}
}
GET /services/:service_code/:environment_name/instances/:id
Retrieve an instance in a given environment.
| Attributes | |
|---|---|
id string |
The id of the instance. This is a canonized id from azure which is the form of /subscriptions/${subscriptionid}/resourceGroups/${resourcegroup}/providers/Microsoft.Compute/virtualMachines/${instanceName}. |
name string |
The name of the instance. |
machineTypestring |
The type of machine assigned for this instance. |
numberOfCoresint |
The number of cores provisioned for this instance. This is determined by the machine type. |
memoryInGBint |
The number of memory in GB provisioned for this instance. This is determined by the machine type. |
imagePublisherstring |
The publisher of the instance used to create the instance. |
imageOfferstring |
The image offer that was used to create the instance. |
imageSkustring |
The image SKU that was used to create the instance. |
imageVersionstring |
The image version that was used to create the instance. |
osTypestring |
The OS type of the instance. This can be either Windows or Linux. |
displayImagestring |
Displayable value of the image information. |
regionstring |
The region in which the instance is located. |
privateIpstring |
The private ip address assigned to the instance. |
internalFqdnstring |
The internal FQDN assigned to the instance. |
macAddressstring |
The MAC address assigned to the instance. |
subnetNamestring |
The name of the subnet that the instance is part of. |
networkNamestring |
The name of the network that the instance is part of. |
supportsPremiumIOboolean |
If the instance supports Premium disks. This is fixed by the machine type. |
supportsUltraIOboolean |
If the instance supports Ultra disks. This is fixed by the machine type. |
attachableDiskSlotsinteger |
The number of managed disks that can be attached to the instance. This is fixed by the machine type. |
usedLunsarray |
An array of all the LUNs associated with the managed disks attached to this instance. |
publicIpstring |
The public ip address assigned to the instance. |
powerStatestring |
The status of the instance. One of the following values: PowerState/running, PowerState/deallocating, PowerState/deallocated, PowerState/starting, PowerState/stopped, PowerState/stopping and PowerState/unknown. |
displayPowerStatestring |
The status of the instance. One of the following values: running, deallocating, deallocated, starting, stopped, stopping and unknown. |
networkInterfaceslist |
A list of network interfaces of the instance. Contains fields: id, name, primary. |
Create an instance
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/azure/example/instances"
Request body examples:
// Create an instance using ssh key authentication
{
"name": "new-server",
"machineType": "Standard_B1ls",
"imagePublisher": "CoreOS",
"imageOffer": "CoreOS",
"imageSku": "Stable",
"imageVersion": "1010.5.0",
"region": "canadacentral",
"subnet": "/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/virtualNetworks/vn_example_lud/subnets/default",
"username": "johndoe",
"sshkey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCguvgDRuUF/wijOJCNmYlQHujCmUHl/i0Ubos4nHy5uCBdn1LGF+PG3TpJqO1LUWqpHaPl4yN7bpsdXyq6a9nxe0C1bQ4FK6P5qm0X320uvqv34jwTPsIbnhw9I317df+xJyXXsL/P5vS4ULPMC5UZjWm4BYe7did4zmXXhA/zmLY6cUg19sZp5r5SUQcf5xHAqO3cQVZwzBhBMwroflZZ59zNpxy+xXPBqC3IdusF2yTDW7bwCQHESUOsd9XhwrzCB+1wETKjLpk0wkWj8G2j1pkKGRpv60QcG85lbZvQAg54v3HYD7fVJCaz9gJJoiyRBnqQ6XVxam5bZgiMKa0J johndoe@machine.local"
}
// Create an instance using password authentication
{
"name": "new-server",
"machineType": "Standard_B1ls",
"imagePublisher": "CoreOS",
"imageOffer": "CoreOS",
"imageSku": "Stable",
"imageVersion": "1010.5.0",
"region": "canadacentral",
"subnet": "/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/virtualNetworks/vn_example_lud/subnets/default",
"username": "johndoe",
"password": "SomePassw0rdVal!d"
}
The above command(s) return(s) JSON structured like this:
{
"taskId": "00b76dbe-f9de-4f2b-9434-5a7d93fb7112",
"taskStatus": "PENDING"
}
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/tasks/00b76dbe-f9de-4f2b-9434-5a7d93fb7112"
The above command(s) return(s) JSON structured like this:
{
"data": {
"id": "00b76dbe-f9de-4f2b-9434-5a7d93fb7112",
"status": "SUCCESS",
"created": "2021-04-20T20:58:59.952881-04:00",
"result": {
"username": "johndoe",
"password": "SomePassw0rdVal!d",
...
}
}
}
POST /services/:service_code/:environment_name/instances
Create a new instance.
| Required | |
|---|---|
name string |
The name of the instance. The name cannot exceed 64 characters. |
machineTypestring |
The type of machine assigned for this instance. |
imagePublisherstring |
The image publisher from which the image is selected. |
imageOfferstring |
The image offer that was used to create the instance. |
imageSkustring |
The image SKU that was used to create the instance. |
imageVersionstring |
The image version that was used to create the instance. |
regionstring |
The region in which the instance is located. |
subnetstring |
The subnet id that the instance will be part of. |
usernamestring |
The administrator username which will be created on the instance. It cannot be a reserve user such as admin, root or administrator and must not be more than 20 characters. |
| Optional | |
|---|---|
passwordstring |
The password of the administrator account. It must be between between 12 and 72 characters and must be a combination of 3 of the following patterns : Special characters, Uppercase, Lowercase and Numbers. The password is mandatory if the SSH key is not provided. |
sshkeystring |
The SSH key public portion that will be assigned to the user on the machine. This cannot be used for a Windows based OS. |
publicIpAddressIdstring |
The fully qualified id of the public IP address to associate to the instance. |
| Attributes | |
|---|---|
idstring |
The task's ID. |
statusstring |
The task's status. |
createdDate |
The task's creation date. |
resultObject |
The task result, containing details of the newly created instance. |
result.securityTypestring |
The security type used to secure the instance. Either password or sshKey. |
result.usernamestring |
The administrator username created on the instance. |
result.passwordstring |
The password for the newly created instance. Only set if password authentication is configured on the instance. |
result.sshkeystring |
The SSH key for the newly created instance. Only set if SSH key authentication is configured on the instance. |
Delete an instance
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/azure/example/instances/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Compute/virtualMachines/example-small-server"
DELETE /services/:service_code/:environment_name/instances/:id
Delete an existing instance.
| Query Parameter | |
|---|---|
deleteOsDiskboolean |
Will delete the OS disk attached to this instance. Default value is false. |
Change machine type
A machine type determines the number of vCPUs and the size of the memory allocated to the instances.
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/azure/example/instances/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Compute/virtualMachines/example-small-server?operation=resize"
Request body example:
{
"machineType": "Standard_B1ls"
}
POST /services/:service_code/:environment_name/instances/:id?operation=resize
Update the machine type for the existing instance.
| Required | |
|---|---|
machineTypestring |
The new machine type to assign to the instance. |
Reset password
Reset the administrator password on Windows or Linux instances.
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/azure/example/instances/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Compute/virtualMachines/example-small-server?operation=reset_password"
Request body example:
{
"password": "my-new-password"
}
The above command(s) return(s) JSON structured like this:
{
"taskId": "00b76dbe-f9de-4f2b-9434-5a7d93fb7112",
"taskStatus": "PENDING"
}
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/tasks/00b76dbe-f9de-4f2b-9434-5a7d93fb7112"
The above command(s) return(s) JSON structured like this:
{
"data": {
"id": "00b76dbe-f9de-4f2b-9434-5a7d93fb7112",
"status": "SUCCESS",
"created": "2021-04-20T20:58:59.952881-04:00",
"result": {
"username": "johndoe",
"password": "my-new-password",
...
}
}
}
POST /services/:service_code/:environment_name/instances/:id?operation=reset_password
For Linux instances, reset the administrator account. For Windows instances, reset the administrator account and reset the Remote Desktop service configuration.
| Optional | |
|---|---|
passwordstring |
The password of the administator account. It must be between between 12 and 72 characters and must be a combination of 3 of the following patterns : Special characters, Uppercase, Lowercase and Numbers. If not provided, a new password is generated. |
| Attributes | |
|---|---|
idstring |
The task's ID. |
statusstring |
The task's status. |
createdDate |
The task's creation date. |
resultObject |
The task result, containing details of the password reset. |
result.usernamestring |
The administrator username created on the instance. |
result.passwordstring |
The password for the newly created instance. |
Start an instance
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/azure/example/instances/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Compute/virtualMachines/example-small-server?operation=start"
POST /services/:service_code/:environment_name/instances/:id?operation=start
Start an existing instance. The instance must be in the power state PowerState/deallocated or PowerState/stopped for this operation to work.
Stop an instance
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/azure/example/instances/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Compute/virtualMachines/example-small-server?operation=stop"
POST /services/:service_code/:environment_name/instances/:id?operation=stop
Stop an existing instance. The instance must be in either the power state PowerState/running or PowerState/starting status for this operation to work.
Attach a disk (instance side)
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/azure-conn/test_env/instances/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/instances/{instanceName}?operation=attach_disk"
Request body example:
{
"diskToAttach" : "disktest1",
"diskLun": 10
}
The above command returns a JSON structured like this:
{
"taskId": "802c5ae0-8431-47dc-9abe-7e10a9badddc",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/instances/:id?operation=attach_disk
| Required | |
|---|---|
diskToAttach String |
The Id of the disk that you want to be attached to the instance. |
diskLunInteger |
The logic unit number of a disk. Can only be between 1 and 63 inclusive. |
Regions
A region is location where Azure resources are physically deployed. They can be whitelisted in the service configuration for an Azure connection in CloudMC.
List regions
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/azure/example/regions"
The above command returns a JSON structured like this:
{
"data": [
{
"name": "eastasia"
},
{
"name": "eastus"
}
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/regions
Retrieve a list of all regions enabled.
| Attributes | |
|---|---|
namestring |
The name of the region. |
Retrieve a region
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/azure/example/regions/useast"
The above command returns a JSON structured like this:
{
"data": {
"name": "eastus"
}
}
GET /services/:service_code/:environment_name/regions/:name
Retrieve a specific enabled region.
| Attributes | |
|---|---|
namestring |
The name of the region. |
Storage
Disks
Deploy and manage your disks.
For information regarding azure disks, please see azure docs.
List disks
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/azure-conn/test_env/disks"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "/subscriptions/6b6a1f27-55c1-4b1d-969b-60a3c9eebe64/resourceGroups/azure-connect-system-ssamadh-mean-env/providers/Microsoft.Compute/disks/ssamadh-basic",
"name": "ssamadh-basic",
"type": "premium_lrs",
"region": "southeastasia",
"state": "unattached",
"provisioningState": "succeeded",
"creationDate": "2020-02-05T19:17:43.749Z",
"sizeInBytes": 8589934592,
"iops": 120,
"throughputInMBps": 25,
"dataDisk": true,
"isAttachedToInstance": false
},
{
"id": "/subscriptions/6b6a1f27-55c1-4b1d-969b-60a3c9eebe64/resourceGroups/azure-connect-system-ssamadh-mean-env/providers/Microsoft.Compute/disks/the-sheep_disk1_e93bd2519aac4c0cbe27c49aa928525e",
"name": "the-sheep_disk1_e93bd2519aac4c0cbe27c49aa928525e",
"type": "premium_lrs",
"osType": "Linux",
"region": "eastasia",
"instanceId": "/subscriptions/6b6a1f27-55c1-4b1d-969b-60a3c9eebe64/resourceGroups/azure-connect-system-ssamadh-mean-env/providers/Microsoft.Compute/virtualMachines/the-sheep",
"instance": "the-sheep",
"state": "attached",
"provisioningState": "succeeded",
"creationDate": "2020-02-05T21:02:36.062Z",
"sizeInBytes": 32213303296,
"iops": 120,
"throughputInMBps": 25,
"dataDisk": false,
"isAttachedToInstance": true
},
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/disks
Retrieve a list of all the disks in a given environment.
| Attributes | |
|---|---|
dataarray |
A list of Azure disks. (See "Retrieve an Azure disk" API for the strucutre of each disk object) |
metadataobject |
Consists of the meta information related to the returned disk list. The attribute recordCount contains the number of disks returned. |
Retrieve an Azure disk
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/azure-conn/test_env/disks/subscriptions/60a3c9eebe64-55c1-4b1d-969b-60a3c/resourceGroups/azure-connect-system-ssamadh-mean-env/providers/Microsoft.Compute/disks/the-sheep_disk1_c0cbe27c49aa928525e93bd2519aac4"
The above command returns a JSON structured like this:
{
"id": "/subscriptions/6b6a1f27-55c1-4b1d-969b-60a3c9eebe64/resourceGroups/azure-connect-system-ssamadh-mean-env/providers/Microsoft.Compute/disks/the-sheep_disk1_e93bd2519aac4c0cbe27c49aa928525e",
"name": "the-sheep_disk1_e93bd2519aac4c0cbe27c49aa928525e",
"type": "premium_lrs",
"osType": "Linux",
"region": "eastasia",
"instanceId": "/subscriptions/6b6a1f27-55c1-4b1d-969b-60a3c9eebe64/resourceGroups/azure-connect-system-ssamadh-mean-env/providers/Microsoft.Compute/virtualMachines/the-sheep",
"instance": "the-sheep",
"state": "attached",
"provisioningState": "succeeded",
"creationDate": "2020-02-05T21:02:36.062Z",
"sizeInBytes": 32213303296,
"iops": 120,
"throughputInMBps": 25,
"dataDisk": false,
"isAttachedToInstance": true
}
GET /services/:service_code/:environment_name/disks/:id
Retrieve a specific disk in a given environment.
| Attributes | |
|---|---|
idstring |
The id of the disk. This is a canonized id from azure which is the form of /subscriptions/${subscriptionid}/resourceGroups/${resourcegroup}/providers/Microsoft.Compute/disks/${diskName} |
namestring |
The display name of the disk |
typestring |
The managed disk type. Can be one of the following: premium_lrs (Premium SSD), standard_lrs (Standard HDD), standardssd_lrs (Standard SSD) or ultrassd_lrs (Ultra SSD) |
regionstring |
The regional location in which the disk was instantiated |
instanceIdstring |
The id of the instance to which the disk is attached to. This is a canonized id from azure which is the form of /subscriptions/${subscriptionid}/resourceGroups/${resourcegroup}/providers/Microsoft.Compute/virtualMachines/${instanceName} |
instancestring |
The name of the instance to which the disk is attached to (available only if the disk is attached to an instance) |
statestring |
An indication of the state of the disk. Can be one of the following: Unattached, Attached, Reserved, ActiveSAS, ReadyToUpload, ActiveUpload |
provisioningStatestring |
An indication of the provisioning state of the disk (SUCCESS or FAILURE) |
creationDatestring |
The date in which the disk was created |
sizeInByteslong |
The size of the disk in bytes |
iopslong |
The number of IOPS allowed for this disk (only settable for UltraSSD disks). One operation can transfer between 4k and 256k bytes. |
throughputInMBpslong |
The bandwidth allowed for this disk; only settable for UltraSSD disks. MBps means millions of bytes per second - MB here uses the ISO notation, of powers of 10. |
dataDiskboolean |
Indication of whether the disk is a DATA disk. If false then it's an OS disk |
isAttachedToInstanceboolean |
An indication of whether the disk has been attached to an Azure instance |
Create a disk
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-d "request_body"
"https://cloudmc_endpoint/api/v2/services/azure/example/disks"
Request body example:
{
"name":"ad_root_smean",
"region":"northeurope",
"type":"ultrassd_lrs",
"sizeGb":"200",
"iops": "40",
"throughputInMBps": "200"
}
The above command returns a JSON structured like this:
{
"taskId": "802c5ae0-8431-47dc-9abe-7e10a9badddc",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/disks
(Use the task API to get the status of the operation)
Create a disk in an environment.
| Attributes | |
|---|---|
namestring |
The name of the azure disk. Supported characters for the name are a-z, A-Z, 0-9 and _; The maximum name length is 80 characters |
regionstring |
The azure region in which the disk is to be created. See list of regions here |
typestring |
The managed disk type. Can be one of the following:premium_lrs, standard_lrs, standardssd_lrs, ultrassd_lrs |
sizeGbstring |
The size of the disk |
iopsstring |
The number of read/write operations per second on the disk(Only supported for disks of type ultrassd_lrs) |
throughputInMBpsstring |
The throughput of the disk(Only supported for disks of type ultrassd_lrs) |
Edit a disk
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-d "request_body"
"https://cloudmc_endpoint/api/v2/services/azure-conn/test_env/disks/subscriptions/60a3c9eebe64-55c1-4b1d-969b-60a3c/resourceGroups/azure-connect-system-ssamadh-mean-env/providers/Microsoft.Compute/disks/the-sheep_disk1_c0cbe27c49aa928525e93bd2519aac4"
Request body examples:
{
"type":"standardssd_lrs",
"sizeGb":"200",
}
{
"iops": "40",
"throughputInMBps": "200"
}
The above commands return JSON structured like this:
{
"taskId": "802c5ae0-8431-47dc-9abe-7e10a9badddc",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/disks/:id
(Use the task API to get the status of the operation)
Edit a disk in an environment.
| Optional | |
|---|---|
typestring |
The managed disk type. Can only be one of the following:premium_lrs, standard_lrs, standardssd_lrsUpdating the type of an Ultra disk is not allowedUpdating the type to ultrassd_lrs is also not allowed |
sizeGbstring |
The size of the disk Disk size can only be increased during an update Updating the disk size of Ultra disks are not allowed |
iopsstring |
The number of read/write operations per second on the disk(Only supported for disks of type ultrassd_lrs) |
throughputInMBpsstring |
The throughput of the disk(Only supported for disks of type ultrassd_lrs) |
Note: If the disk is attached to an instance, then the attached instance will be deallocated (removed from the host hypervisor) before the disk update and will be restored back to its original power state.
Delete a disk
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/azure-conn/test_env/disks/subscriptions/60a3c9eebe64-55c1-4b1d-969b-60a3c/resourceGroups/azure-connect-system-ssamadh-mean-env/providers/Microsoft.Compute/disks/the-sheep_disk1_c0cbe27c49aa928525e93bd2519aac4"
DELETE /services/:service_code/:environment_name/disks/:id
Destroy an existing disk. A disk can only be deleted if it's not attached to an instance.
Detach a disk
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/azure-conn/test_env/disks/subscriptions/60a3c9eebe64-55c1-4b1d-969b-60a3c/resourceGroups/azure-connect-system-ssamadh-mean-env/providers/Microsoft.Compute/disks/the-sheep_disk1_c0cbe27c49aa928525e93bd2519aac4?operation=detach"
POST /services/:service_code/:environment_name/disks/:id?operation=detach
Detach an existing disk from a given instance.
Attach a disk (disk side)
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/azure-conn/test_env/disks/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/disks/{diskName}?operation=attach"
Request body examples:
{
"instance" : "cool-instance",
}
{
"instance" : "cool-instance",
"lun" : 10
}
The above command returns a JSON structured like this:
{
"taskId": "802c5ae0-8431-47dc-9abe-7e10a9badddc",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/disks/:id?operation=attach
Attach a disk to an instance.
| Optional | |
|---|---|
lunInteger |
The logic unit number of a disk. Can only be between 1 and 63 inclusive. If the LUN is not specified it will default to the first available LUN for that instance. |
Networking
Virtual Networks
A virtual network is an isolated network where you can place groups of resources, such as instances.
List virtual networks
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/azure/example/networks"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "/subscriptions/subscription/resourceGroups/example-system-azure-example/providers/Microsoft.Network/virtualNetworks/sample-network",
"name": "sample-network",
"region": "canadacentral",
"provisioningState": "Succeeded",
"addressSpace": [
"10.2.0.0/16"
]
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/networks
Retrieve a list of all virtual networks in an environment.
| Optional query parameters | |
|---|---|
subnetListboolean |
If set to true, it will also include the subnet information in the list. |
| Attributes | |
|---|---|
idstring |
The id associated to the virtual network. This is a canonized id from azure which is the form of /subscriptions/:subscriptionid/resourceGroups/:resourcegroup/providers/Microsoft.Network/virtualNetworks/:networkName |
namestring |
The name of the virtual network |
regionstring |
The region in which the virtual network is located |
provisioningStatestring |
The provisioning state of the virtual network. Possible values are : Succeeded, Updating, Deleting and Failed |
addressSpacelist |
List of address space that are covered by this virtual network |
Create virtual networks
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-d "request_body"
"https://cloudmc_endpoint/api/v2/services/azure/example/networks"
Request body example:
{
"name": "simpleNetwork",
"region" : "canadaeast",
"addressSpace": "10.0.0.0/16",
"subnetName": "default",
"subnetAddressPrefix": "10.0.0.0/16"
}
POST /services/:service_code/:environment_name/networks
Create a virtual network in an environment.
| Attributes | |
|---|---|
namestring |
The name of the virtual network |
regionstring |
The region in which the virtual network is located |
addressSpacestring |
The first address range (IPV4 CIDR format) that will be covered by this virtual network |
subnetNamestring |
The first subnet name within this virtual network |
subnetAddressPrefixstring |
The first subnet address range (IPV4 CIDR format) within this virtual network |
networkSecurityGroupIdstring |
The id of the network security group for the subnet, can also enter NONE or omit the field. |
Subnets
A subnet is a child of a virtual network. It is a subset of a network in which IP addresses point to the same group.
List subnets
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/azure/example/subnets"
The above command returns a JSON structured like this:
{
"data": [
{
"addressPrefix": "10.1.2.0/24",
"parentNetworkId": "/subscriptions/:subscription/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/example-vnet",
"parentNetworkName": "example-vnet",
"allocatedIpAddresses": 3,
"availableAddresses": 248,
"totalNumberIps": 251,
"id": "/subscriptions/:subscription/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/example-vnet/subnets/example-subnet",
"region": "eastus",
"name": "example-subnet"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/subnets
Retrieve a list of all subnets in an environment. If the network filter is included, the response bodies will contain additional details specified below.
| Query parameters | |
|---|---|
network_idstring |
The id for the network who's subnets you're fetching. Only subnets of the passed network will be returned. |
| Attributes | |
|---|---|
idstring |
The id associated to the subnet. This is a canonized id from azure which is the form of /subscriptions/:subscriptionid/resourceGroups/:resourcegroup/providers/Microsoft.Network/virtualNetworks/:networkName/subnets/:subnetName |
parentNetworkId string |
The id for the parent network. |
parentNetworkName string |
The name for the parent network. |
namestring |
The name of the subnet. |
regionstring |
The region in which the parent of the subnet is located. |
allocatedAddressesint |
The number of allocated addresses in the subnet. |
availableAddressesint |
The number of available ip addresses in the subnet. |
totalNumberIpsint |
The total number of ip addresses in the address space of the subnet. |
| Additional Attributes: Network filter included | |
|---|---|
networkSecurityGroupIdstring |
The id of the network security group for the subnet, if it exists. |
networkSecurityGroupName string |
The name of the network security group for the subnet, if it exists. |
nicslist |
A list of nics associated to the subnet. |
nics.namestring |
The name of the nic. |
nics.primaryPrivateIpstring |
The primary private ip for the nic. |
nics.idstring |
The id for the nic. |
nics.subnetNamestring |
The name for the subnet to which to the nic belongs. |
nics.networkNamestring |
The name for the network to which to the nic belongs. |
Retrieve a subnet
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/azure/example/subnets/subscriptions/mySubscription/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/example-vnet/subnets/example-subnet"
The above command returns a JSON structured like this:
{
"data": {
"addressPrefix": "10.1.2.0/24",
"parentNetworkId": "/subscriptions/mySubscription/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/example-vnet",
"parentNetworkName": "example-vnet",
"allocatedIpAddresses": 3,
"availableAddresses": 248,
"totalNumberIps": 251,
"id": "/subscriptions/mySubscription/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/example-vnet/subnets/example-subnet",
"region": "eastus",
"name": "example-subnet",
"networkSecurityGroupName": "test-rg",
"nics": [
{
"name": "sample-nic",
"subnetName": "example-subnet",
"subnetName": "example-vnet",
"primaryPrivateIp": "10.1.2.4",
"id": "/subscriptions/mySubscription/resourceGroups/myResourceGroup/providers/networkInterfaces/virtualNetworks/sample-nic"
}
]
}
}
GET /services/:service_code/:environment_name/subnets/:subnet_id
Retrieve a specific subnet by id.
| Attributes | |
|---|---|
addressPrefixstring |
The IPv4 CIDR representing the address range for the subnet. |
idstring |
The id associated to the subnet. This is a canonized id from azure which is the form of /subscriptions/:subscriptionid/resourceGroups/:resourcegroup/providers/Microsoft.Network/virtualNetworks/:networkName/subnets/:subnetName |
parentNetworkId string |
The id for the parent network. |
parentNetworkName string |
The name for the parent network. |
namestring |
The name of the subnet. |
regionstring |
The region in which the parent of the subnet is located. |
allocatedAddressesint |
The number of allocated addresses in the subnet. |
availableAddressesint |
The number of available ip addresses in the subnet. |
totalNumberIpsint |
The total number of ip addresses in the address space of the subnet. |
networkSecurityGroupIdstring |
The id of the network security group for the subnet, if it exists. |
networkSecurityGroupName string |
The name of the network security group for the subnet, if it it exists. |
nicslist |
A list of nics associated to the subnet. |
nics.namestring |
The name of the nic. |
nics.primaryPrivateIpstring |
The primary private ip for the nic. |
nics.idstring |
The id for the nic. |
nics.subnetNamestring |
The name for the subnet to which to the nic belongs. |
nics.networkNamestring |
The name for the network to which to the nic belongs. |
Create a subnet
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/azure/example/subnets"
Request body example:
{
"name": "default",
"addressPrefix": "10.0.1.0/24",
"parentNetworkId": "/subscriptions/mySubscription/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/example-vnet"
}
POST /services/:service_code/:environment_name/subnets
Create a new subnet.
| Required | |
|---|---|
name string |
The name of the subnet. The name cannot exceed 80 characters. |
addressPrefix string |
The portion of the parent network's address space (IPV4 CIDR format) allocated to the subnet. The range cannot overlap with other subnets. The smallest range you can specify is /29. |
parentNetworkId string |
The subnet's parent network id. |
| Optional | |
|---|---|
networkSecurityGroupIdstring |
The id for the network security group you want to associate the subnet to, can be NONE. |
Update a Subnet
curl -X PUT \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/azure/example/subnets/subscriptions/mySubscription/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/example-vnet/subnets/example-subnet"
Request body example:
{
"addressPrefix":"This is my updated template description"
}
PUT /services/:service_code/:environment_name/subnets/:subnet_id
Update a subnet.
| Optional | |
|---|---|
addressPrefixstring |
The portion of the parent network's address space (IPV4 CIDR format) allocated to the subnet. The range cannot overlap with other subnets. The smallest range you can specify is /29. Can only be updated if it is contained within the range of the parent network and if no resources are attached to the subnet. |
networkSecurityGroupIdstring |
The id for the network security group you want to associate the subnet to, NONE if you want to detach the current network security group. |
Delete a subnet
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/azure/example/subnets/subscriptions/mySubscription/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/example-vnet/subnets/example-subnet"
DELETE /services/:service_code/:environment_name/subnets/:subnet_id
Deletes a specific subnet by id.
| Attributes | |
|---|---|
idstring |
The id associated to the subnet. This is a canonized id from azure which is the form of /subscriptions/:subscriptionid/resourceGroups/:resourcegroup/providers/Microsoft.Network/virtualNetworks/:networkName/subnets/:subnetName |
Network Security Groups
A network security group is a group of security rules that allow or deny inbound network traffic to, or outbound network traffic from, several types of Azure resources, including Azure virtual networks.
List network security groups
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/azure/example/networksecuritygroups"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "/subscriptions/subscription/resourceGroups/example-system-azure-example/providers/Microsoft.Network/networksecuritygroups/sample-network-security-group",
"name": "sample-network-security-group",
"region": "canadacentral",
"provisioningState": "Succeeded",
"defaultSecurityRules": [
{
"name": "SampleRule",
"id": "/subscriptions/subscription/resourceGroups/example-system-azure-example/providers/Microsoft.Network/networksecuritygroups/sample-network-security-group/defaultSecurityRules/SampleRuleInBound",
"direction": "Inbound"
}],
"customSecurityRules": [],
"numberInbound": 3,
"numberOutbound": 3,
"numberAssociatedSubnets": 0,
"numberAssociatedNetworkInterfaces": 0
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/networksecuritygroups
Retrieve a list of all network security groups in an environment.
| Attributes | |
|---|---|
idstring |
The id associated to the network security group. This is a canonized id from azure which is the form of /subscriptions/:subscriptionid/resourceGroups/:resourcegroup/providers/Microsoft.Network/networksecuritygroups/:networkSecurityGroupName |
namestring |
The name of the network security group. |
regionstring |
The region in which the network security group is located |
provisioningStatestring |
The provisioning state of the network security group. Possible values are : Succeeded, Updating, Deleting and Failed |
defaultSecurityRulesList |
The default security rules of network security group |
customSecurityRulesList |
A collection of security rules of the network security group |
numberInboundint |
The number of security rules (default and custom) which are inbound |
numberOutboundint |
The number of security rules (default and custom) which are outbound |
numberAssociatedSubnetsint |
The number of subnets associated with this network security group |
numberAssociatedNetworkInterfacesint |
The number of network interfaces associated with this network security group |
Create a network security group
curl -X POST \
'http://cloudmc_endpoint/v1/services/azure/my-azure/networkSecurityGroups' \
-H 'mc-api-key: your_api_key' \
-d '{
"name": "network-security-group",
"region": "eastus"
}'
POST /services/:service_code/:environment_name/networkSecurityGroups
Create a new network security group.
| Required | |
|---|---|
name string |
The name of the network security group. The name cannot exceed 64 characters |
regionstring |
The region in which the network security group is located |
Delete a network security group
curl -X DELETE \
'http://cloudmc_endpoint/v1/services/azure/my-azure/networkSecurityGroups/subscriptions/6b6a1f27-55c1-4b1d-969b-60a3c9eebe64/resourceGroups/azure-system-co-cloudmc-eastus/providers/Microsoft.Network/networkSecurityGroups/test' \
-H 'mc-api-key: your_api_key'
DELETE /services/:service_code/:environment_name/networkSecurityGroups/:id
Delete an existing network security group.
Security Rules
A security rule in Azure is a filter which controls both inbound and outbound traffic on a network security group attacted to the ressource that receives the traffic.
List security rules
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/azure/example/securityrules"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/networksecuritygroups/sample-network-security-group/defaultSecurityRules/SampleRuleInBound",
"name": "SampleRule",
"direction": "Inbound",
"access": "Deny",
"priority": 110,
"protocol": "Udp",
"sourcePortRanges": [
"1024"
],
"sources": [
"0.0.0.1",
"10.0.0.0/32"
],
"destinationPortRanges": [
"8080"
],
"destinations": [
"10.0.0.0/16"
],
"securityGroupId": "/subscriptions/:subscription/resourceGroups/:resourceGroup/providers/Microsoft.Network/networkSecurityGroups/sample-network-security-group"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/securityrules
Retrieve a list of all security rules in an environment.
| Query parameters | |
|---|---|
security_group_idstring |
The id of the network security group in which we want to fetch the list of security rules. |
directionstring |
Filter on the list of security rules. Either Inbound or Outbound. No value will passed will return a list with both included. |
| Attributes | |
|---|---|
idstring |
The id associated to the security rule. This is a canonized id from azure which is the form of /subscriptions/:subscriptionid/resourceGroups/:resourcegroup/providers/Microsoft.Network/networksecuritygroups/:networkSecurityGroupName/defaultSecurityRules/:securityRuleName if it is a default rule or /subscriptions/:subscriptionid/resourceGroups/:resourcegroup/providers/Microsoft.Network/networksecuritygroups/:networkSecurityGroupName/securityRule/:securityRuleName if it is a custom rule. |
namestring |
The name of the security rule. |
priorityint |
Rules are processed in priority order; the lower the number, the higher the priority. Values are between 100 and 4096. |
directionstring |
Either Inbound or Outbound. |
accessstring |
Determine if rule is allowing or blocking trafic. Either Access or Deny. |
protocolstring |
One of *, TCP, UDP and ICMP. * is allowing any protocol. |
sourcePortRangesList |
This specifies on which ports traffic will be allowed or denied by this rule. If the list is empty then all values are included. |
sourcesList |
List of IP address ranges or/and IP adresses. If the list is empty then all values are included. |
destinationPortRangesList |
This specifies on which ports traffic will be allowed or denied by this rule. If the list is empty then all values are included. |
destinationsList |
List of IP address ranges or/and IP adresses. If the list is empty then all values are included. |
securityGroupIdString |
The id of the network security group to which the rule belongs. |
Retrieve a security rule
curl -X GET \
-H 'mc-api-key: your_api_key' \
"https://cloudmc_endpoint/api/v2/services/azure/example/securityrules/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/networkSecurityGroups/mySecurityGroup/securityRules/mySeccurityRule"
The above command returns a JSON structured like this:
{
"data": {
"id": "/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/networkSecurityGroups/mySecurityGroup/defaultSecurityRules/SampleRuleInBound",
"name": "SampleRuleInBound",
"direction": "Inbound",
"access": "Allow",
"priority": 65001,
"protocol": "*",
"sourcePortRanges": [],
"destinationPortRanges": [],
"destinationAddressPrefixes": [],
"sourceAddressPrefixes": [
"AzureLoadBalancer"
],
"securityGroupId": "/subscriptions/:subscription/resourceGroups/:resourceGroup/providers/Microsoft.Network/networkSecurityGroups/sample-network-security-group"
}
}
GET /services/:service_code/:environment_name/securityrules/:id
Retrieve a specific security rule by rule id.
| Attributes | |
|---|---|
idstring |
The id associated to the security rule. This is a canonized id from azure which is the form of /subscriptions/:subscriptionid/resourceGroups/:resourcegroup/providers/Microsoft.Network/networksecuritygroups/:networkSecurityGroupName/defaultSecurityRules/:securityRuleName if the rule is a default security rule or /subscriptions/:subscriptionid/resourceGroups/:resourcegroup/providers/Microsoft.Network/networksecuritygroups/:networkSecurityGroupName/securityRules/:securityRuleName if the rule is a custom rule. |
namestring |
The name of the security rule. |
priorityint |
The priority of the security rule. |
directionstring |
Either Inbound or Outbound. |
accessstring |
Determine if rule is allowing or blocking trafic. Either Access or Deny. |
protocolstring |
One of *, TCP, UDP and ICMP. * is allowing any protocol. |
sourcePortRangesList |
This specifies on which ports traffic will be allowed or denied by this rule. If the list is empty then all values are included. |
sourcesList |
List of IP address ranges or/and IP adresses. If the list is empty then all values are included. |
destinationPortRangesList |
This specifies on which ports traffic will be allowed or denied by this rule. If the list is empty then all values are included. |
destinationsList |
List of IP address ranges or/and IP adresses. If the list is empty then all values are included. |
securityGroupIdString |
The id of the network security group to which the rule belongs. |
Create a security rule
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-d "request_body"
"https://cloudmc_endpoint/api/v2/services/azure/example/securityrules"
Request body example:
{
"securityGroupId": "/subscriptions/subscription/resourceGroups/example-system-azure-example/providers/Microsoft.Network/networksecuritygroups/sample-network-security-group",
"name": "SampleRule",
"priority": 110,
"direction": "Inbound",
"access": "Deny",
"protocol": "Udp",
"sourcePortRanges": [
"1024"
],
"sources": [
"0.0.0.1",
"10.0.0.0/32"
],
"destinationPortRanges": [
"8080"
],
"destinations": [
"10.0.0.0/16"
]
}
POST /services/:service_code/:environment_name/securityrules
Create a new network security rule in an existing security group.
| Required | |
|---|---|
securityGroupIdstring |
The id of the network security group in which we want to create the security rule. |
namestring |
The name of the security rule. |
priorityint |
Rules are processed in priority order; the lower the number, the higher the priority. Values are between 100 and 4096. |
directionstring |
Either Inbound or Outbound. |
accessstring |
Determine if rule is allowing or blocking trafic. Either Access or Deny. |
protocolstring |
One of *, TCP, UDP and ICMP. * is allowing any protocol. |
| Optional | |
|---|---|
sourcePortRangesList |
This specifies on which ports traffic will be allowed or denied by this rule. If the list is empty then all values are included. |
sourcesList |
List of IP address ranges or/and IP adresses. If the list is empty then all values are included. |
destinationPortRangesList |
This specifies on which ports traffic will be allowed or denied by this rule. If the list is empty then all values are included. |
destinationsList |
List of IP address ranges or/and IP adresses. If the list is empty then all values are included. |
Delete a security rule
curl -X DELETE \
-H 'mc-api-key: your_api_key' \
"https://cloudmc_endpoint/api/v2/services/azure/example/securityrules/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/sample-network-security-group/securityRules/securityRule1"
DELETE /services/:service_code/:environment_name/securityrules/:id
Delete an existing security rule.
Edit a security rule
curl -X POST \
-H 'mc-api-key: your_api_key' \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/azure/example/securityrules/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/networkSecurityGroups/mySecurityGroup/securityRules/mySecurityRule?operation=edit"
Request body example:
{
"access": "Allow",
"priority": 180,
"protocol": "Tcp",
"sourcePortRanges": [],
"sources": [
"10.0.0.0/24"
],
"destinationPortRanges": [
"8080"
],
"destinations": [
"192.168.99.0"
]
}
POST /services/:service_code/:environment_name/securityrules/:id?operation=edit
Update a specific security rule.
| Attributes | |
|---|---|
idstring |
The id associated to the security rule. This is a canonized id from azure which is the form of /subscriptions/:subscriptionid/resourceGroups/:resourcegroup/providers/Microsoft.Network/networksecuritygroups/:networkSecurityGroupName/defaultSecurityRules/:securityRuleName if the rule is a default security rule or /subscriptions/:subscriptionid/resourceGroups/:resourcegroup/providers/Microsoft.Network/networksecuritygroups/:networkSecurityGroupName/securityRules/:securityRuleName if the rule is a custom rule. |
accessstring |
Determine if rule is allowing or blocking trafic. Either Access or Deny. |
priorityint |
The priority of the security rule. |
protocolstring |
One of *, TCP, UDP and ICMP. * is allowing any protocol. |
sourcePortRangesList |
This specifies on which ports traffic will be allowed or denied by this rule. If the list is empty then all values are included. |
sourcesList |
List of IP address ranges or/and IP adresses. If the list is empty then all values are included. |
destinationPortRangesList |
This specifies on which ports traffic will be allowed or denied by this rule. If the list is empty then all values are included. |
destinationsList |
List of IP address ranges or/and IP adresses. If the list is empty then all values are included. |
Public IP addresses
Deploy and manage your public ip addresses.
List public IP addresses
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/azure/example/publicipaddresses"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/publicIPAddresses/some-public-ip",
"name": "some-public-ip",
"state": "DETACHED",
"ipAddress": "52.122.12.1",
"region": "eastus",
"domainName": "somepublicip",
"fqdn": "somepublicip.eastus.cloudapp.azure.com",
"sku": "BASIC",
"idleTimeout": 7,
"allocationMethod": "DYNAMIC",
"ipVersion": "IPV4"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/publicipaddresses
Retrieve a list of all public IP addresses in a given environment
| Attributes | |
|---|---|
id string |
The id of the public IP address. This is a canonized id from azure which is the form of /subscriptions/:subscriptionid/resourceGroups/:resourcegroup/providers/Microsoft.Network/publicIPAddresses/:publicIpName. |
name string |
The name of the public IP address. |
state string |
The state of the public IP address. Possible state: ATTACHED, DETACHED, UPDATING, DELETING. |
ipAddress string |
The IP address of the public IP. If the public IP has never been associated before, then you won't have an ip address yet. |
region string |
The region where the public IP address is located. |
sku string |
The sku of the public IP. Possible values: BASIC, STANDARD. |
domainName string |
The subdomain part of the fqdn. This is only present if one is defined. |
fqn string |
The fqdn which points to the public IP. |
idleTimeout integer |
The number of minutes for the idleTimeout. It can be between 4 and 30 minutes. |
allocationMethod string |
Allocation method of the public IP address. Possible values: DYNAMIC, STATIC. |
ipVersion string |
IP version of the public IP address. Possible values: IPV4, IPV6. |
Retrieve a public ip address
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/azure/example/publicipaddresses/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/publicIPAddresses/some-public-ip"
The above command returns a JSON structured like this:
{
"data": {
"id": "/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/publicIPAddresses/some-public-ip",
"name": "some-public-ip",
"state": "DETACHED",
"ipAddress": "52.122.12.1",
"region": "eastus",
"domainName": "somepublicip",
"fqdn": "somepublicip.eastus.cloudapp.azure.com",
"sku": "BASIC",
"idleTimeout": 7,
"allocationMethod": "DYNAMIC",
"ipVersion": "IPV4"
}
}
GET /services/:service_code/:environment_name/publicipaddresses/:id
Retrieve a public IP address in a given environment.
| Attributes | |
|---|---|
id string |
The id of the public IP address. This is a canonized id from azure which is the form of /subscriptions/:subscriptionid/resourceGroups/:resourcegroup/providers/Microsoft.Network/publicIPAddresses/:publicIpName. |
name string |
The name of the public IP address. |
state string |
The state of the public IP address. Possible state: ATTACHED, DETACHED, UPDATING, DELETING. |
ipAddress string |
The IP address of the public IP. If the public IP has never been associated before, then you won't have an ip address yet. |
region string |
The region where the public IP address is located. |
sku string |
The sku of the public IP. Possible values: BASIC, STANDARD. |
domainName string |
The subdomain part of the fqdn. This is only present if one is defined. |
fqn string |
The fqdn which points to the public IP. |
idleTimeout integer |
The number of minutes for the idleTimeout. It can be between 4 and 30 minutes. |
allocationMethod string |
Allocation method of the public IP address. Possible values: DYNAMIC, STATIC. |
ipVersion string |
IP version of the public IP address. Possible values: IPV4, IPV6. |
Create a public ip address
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-d "request_body"
"https://cloudmc_endpoint/api/v2/services/azure/example/publicipaddresses"
Request body example:
{
"name":"samplePublicIP",
"region" : "canadacentral",
"sku": "BASIC",
"allocationMethod" : "DYNAMIC",
"idleTimeout" : 30,
"domainName" : "samplePublicIP"
}
POST /services/:service_code/:environment_name/publicipaddresses
Create a public IP address in a given environment.
| Required | |
|---|---|
name string |
The name of the public IP address. |
region string |
The region where the public IP address is located. |
| Optional | |
|---|---|
sku string |
The sku of the public IP. Possible values: BASIC, STANDARD. Default value is BASIC. |
allocationMethod string |
Allocation method of the public IP address. Possible values: DYNAMIC, STATIC. Default value is DYNAMIC for SKU BASIC, and STATIC for SKU STANDARD. |
idleTimeout integer |
The number of minutes for the idleTimeout. It can be between 4 and 30 minutes. Default value is 4 minutes. |
domainName string |
The subdomain part of the fqdn. |
Associate a public ip address
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-d "request_body"
"https://cloudmc_endpoint/api/v2/services/azure/example/publicipaddresses?operation=associate"
Request body example:
{
"networkInterfaceId": "subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/networkInterfaces/nic68108672c3b"
}
POST /services/:service_code/:environment_name/publicipaddresses?operation=associate
Associate a public IP address in a given environment to a network interface.
| Required | |
|---|---|
networkInterfaceId string |
Id of the network interface associated to an instance. Th network interface must be in the same region as the public IP address. |
Delete a public IP address
curl -X DELETE \
'http://cloudmc_endpoint/v1/services/azure/example/publicipaddresses/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/publicIPAddresses/some-public-ip' \
-H 'mc-api-key: your_api_key'
DELETE /services/:service_code/:environment_name/publicipaddresses/:id
Delete an existing public IP address.
Update a public ip address
curl -X PUT \
-H "MC-Api-Key: your_api_key" \
-d "request_body"
"https://cloudmc_endpoint/api/v2/services/azure/example/publicipaddresses//subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/publicIPAddresses/some-public-ip"
Request body example:
{
"allocationMethod" : "DYNAMIC",
"idleTimeout" : 30,
"domainName" : "samplePublicIP"
}
PUT /services/:service_code/:environment_name/publicipaddresses/:id
Update a public IP address in a given environment.
| Attribute | |
|---|---|
allocationMethod string |
Allocation method of the public IP address. Possible values: DYNAMIC, STATIC. Not providing it will keep the actual value. Cannot be change for Standard SKU public IP address. |
idleTimeout integer |
The number of minutes for the idleTimeout. It can be between 4 and 30 minutes. Not providing it will keep the actual value. |
domainName string |
The subdomain part of the fqdn. If it is empty or not provided, the entry will be removed from the DNS. |
Kubernetes
Clusters
Deploy and manage your Azure Kubenetes Service (AKS) Clusters.
For information regarding AKS clusters, please see azure docs.
List AKS clusters
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/azure-conn/test_env/clusters"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "/subscriptions/9e548d49-7d56-452c-8fc8-e81a25d05ddf/resourcegroups/azure-connect-system-ssamadh-mean-env/providers/Microsoft.ContainerService/managedClusters/ssamadh-aks-mean",
"name": "ssamadh-basic",
"version": "premium_lrs",
"region": "southeastasia",
"nodePools": "4",
"totalNodes": "7",
},
{
"id": "/subscriptions/ 803c8d4a-80ca-4793-8def-89b5f55d1091/resourcegroups/azure-connect-system-ssamadh-mean-env/providers/Microsoft.ContainerService/managedClusters/ssamadh-aks-mean",
"name": "ssamadh-basic",
"version": "premium_lrs",
"region": "southeastasia",
"nodePools": "2",
"totalNodes": "3",
},
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/clusters
Retrieve a list of all the AKS clusters in a given environment.
| Attributes | |
|---|---|
dataarray |
A list of Azure Kubenetes Service (AKS) Clusters. (See "Retrieve an AKS cluster" API for the strucutre of each AKS cluster object) |
metadataobject |
Consists of the meta information related to the returned cluster list. The attribute recordCount contains the number of clusters returned. |
Retrieve an AKS clusters
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/azure-conn/test_env/clusters/subscriptions/9e548d49-7d56-452c-8fc8-e81a25d05ddf/resourcegroups/azure-connect-system-ssamadh-mean-env/providers/Microsoft.ContainerService/managedClusters/ssamadh-aks-mean"
Note: The above example uses the complete cluster id set by Azure. However, the cluster may also be retrieved by the cluster name as shown below:
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/azure-conn/test_env/clusters/ssamadh-aks-mean"
The above command returns a JSON structured like this:
{
"data": {
"id": "/subscriptions/9e548d49-7d56-452c-8fc8-e81a25d05ddf/resourcegroups/azure-connect-system-ssamadh-mean-env/providers/Microsoft.ContainerService/managedClusters/ssamadh-aks-mean",
"name": "ssamadh-basic",
"version": "premium_lrs",
"region": "southeastasia",
"nodePools": "4",
"totalNodes": "7",
},
}
GET /services/:service_code/:environment_name/clusters/:cluster_name
Retrieve a specific AKS cluster in a given environment.
| Attributes | |
|---|---|
id string |
The resource id |
name string |
The name of the resource, unique within the environment |
provisioningState string |
The state of the cluster could be any of [Succeeded, Creating, Deleting, Updating, Cancelled, Failed] |
dnsPrefixstring |
The DNS prefix specified when creating the managed cluster |
nodePoolsint |
The number of node container service agent pool |
totalNodesint |
The total number of nodes across all nodePools |
rbacEnabledboolean |
Indicates of RBAC is enabled for this kubernetes cluster |
endpointstring |
The fully qualified domain name (fqdn) for the master pool |
regionstring |
The resource location |
version string |
The version of kubernetes running in the cluster |
Create a cluster
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"http://cloudmc_endpoint/v1/services/azure/example/clusters"
Request body examples:
{
"version": "1.18.2",
"dnsPrefix": "kub-root-nik-dns",
"rootUsername": "root_nzk",
"primaryPoolNodeType": "Standard_B2ms",
"primaryPoolNodeCount": 1,
"vmScaleSetsEnabled": false,
"rbacEnabled": false,
"region": "canadacentral",
"name": "kub_root_nzk",
"sshkey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCguvgDRuUF/wijOJCNmYlQHujCmUHl/i0Ubos4nHy5uCBdn1LGF+PG3TpJqO1LUWqpHaPl4yN7bpsdXyq6a9nxe0C1bQ4FK6P5qm0X320uvqv34jwTPsIbnhw9I317df+xJyXXsL/P5vS4ULPMC5UZjWm4BYe7did4zmXXhA/zmLY6cUg19sZp5r5SUQcf5xHAqO3cQVZwzBhBMwroflZZ59zNpxy+xXPBqC3IdusF2yTDW7bwCQHESUOsd9XhwrzCB+1wETKjLpk0wkWj8G2j1pkKGRpv60QcG85lbZvQAg54v3HYD7fVJCaz9gJJoiyRBnqQ6XVxam5bZgiMKa0J johndoe@machine.local"
}
The above command(s) return(s) JSON structured like this:
{
"taskId": "ba0d9e44-ce89-4cc0-9c90-da1dcde1a8ac",
"taskStatus": "PENDING"
}
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/tasks/ba0d9e44-ce89-4cc0-9c90-da1dcde1a8ac"
The above command(s) return(s) JSON structured like this:
{
"data": {
"id": "ba0d9e44-ce89-4cc0-9c90-da1dcde1a8ac",
"status": "SUCCESS",
"created": "2022-06-23T13:11:07.03164-04:00",
"result": {
"rootUsername": "root_nzk",
"sshKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCZcbdHKq1YK4vV5gtemy5SzngDhU3mSGhsxyBe4uKvEwk4shzRBPRc8uvOm0KrzB9KkbuxR3OJ1TbFVijnmvrOGIacN7BsJENBcBsrjjHW3vNPF0ZaJWts+lUPL+6BcuDTNUSyDTpAI1Xs/a3P5E7kOQumiwjlXIwuyJyGIk5Lt2FmZgDSCuZ4fjuUGgQq27RDya7G/eB5eKD9ohmXM567VHWvGQKUV4RdNDM0W4YuQYCAsaLwaKhFMOxr1AK5YOgyJYVVZn280bOx2qDyp6fTN49UTbkOtcQz+S8d2PRLaplY3QVPtelV47s2Gawgl8i3jiXGBbMV6WllLM+ujZy7 ",
...
}
}
}
POST /services/:service_code/:environment_name/clusters
Create a new cluster.
| Required | |
|---|---|
dnsPrefixstring |
The DNS prefix to be used to create the FQDN for the master pool. |
namestring |
. The name of the cluster. |
primaryPoolNodeCountstring |
The number of agents (VMs) to host docker containers. Allowed values must be in the range of 1 to 100 (inclusive). |
primaryPoolNodeTypestring |
The size type of each virtual machine in the agent pool. |
rbacEnabledboolean |
A boolean to indicate whether RBAC should be enabled on this cluster or not. |
regionstring |
The name of the region for the cluster. |
sshkeystring |
The ssh key public portion that will be used to access cluster. |
version string |
The version for the Kubernetes cluster. |
vmScaleSetsEnabledboolean |
The boolean to indicate whether to use virtual machine scale sets or availability set for agent pool. |
| Optional | |
|---|---|
rootUsernamestring |
The user name to create a root user on cluster. |
| Attributes | |
|---|---|
idstring |
The task's ID. |
statusstring |
The task's status. |
createdDate |
The task's creation date. |
resultObject |
The task result, containing details of the newly created cluster. |
result.rootUsernamestring |
The username for the root user on the newly created cluster. |
result.sshKeystring |
The SSH key for the newly created cluster. |
Delete a cluster
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/azure/example/clusters/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.ContainerService/managedClusters/sample_small_cluster"
The above command returns a JSON structured like this:
{
"taskId": "3e4d4466-ce4b-404b-ada5-ee5a3fb76f4e",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/clusters/:id
Delete an existing cluster.
Namespaces
List namespaces
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/namespaces?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "default",
"metadata": {},
"spec": {},
"status": {}
}
],
"metadata": {
"recordCount": 4
}
}
GET /services/:service_code/:environment_name/namespaces?cluster_id=:cluster_id
Retrieve a list of all namespaces in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the namespaces. |
| Attributes | |
|---|---|
id string |
The id of the namespace. |
apiVersion string |
APIVersion defines the versioned schema of this representation of a namespace object |
metadata object |
The metadata of the namespace |
specobject |
The specification describes the attributes on a namespace. |
statusobject |
The status information of the namespace |
Get a namespace
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/namespaces/cert-manager?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "default",
"apiVersion": "v1",
"kind": "Namespace",
"metadata": {},
"spec": {},
"status": {}
}
}
GET /services/:service_code/:environment_name/namespaces/:id?cluster_id=:cluster_id
Retrieve a namespace and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the namespace. |
| Attributes | |
|---|---|
id string |
The id of the namespace. |
apiVersion string |
APIVersion defines the versioned schema of this representation of a namespace object |
metadata object |
The metadata of the namespace |
specobject |
The specification describes the attributes on a namespace. |
statusobject |
The status information of the namespace |
Create a namespace
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/namespaces?cluster_id=test-cluster"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Namespace",
"metadata": {
"name": "test-namespace"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/namespaces?cluster_id=:cluster_id
Create a namespace in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the namespace. |
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the namespace. |
metadata object |
The metadata of the namespace. |
metadata.name string |
The name of the namespace. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create namespace task. |
taskStatus string |
The status of the operation. |
Delete a namespace
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/namespaces/test-namespace?cluster_id=test-cluster"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/namespaces/:id?cluster_id=:cluster_id
Delete a namespace from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the namespace. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete namespaces task. |
taskStatus string |
The status of the operation. |
Workloads
Pods
List pods
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/pods?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "my-aerospike-0/default",
"metadata": {
"annotations": {
"checksum/config": "0e07919467cc16f2c07ac99d0036405deafa06f7d3b430215915470b3a6ca631"
},
"creationTimestamp": "2020-01-20T09:35:02.000-05:00",
"generateName": "my-aerospike-",
"labels": {
"app": "aerospike",
"controller-revision-hash": "my-aerospike-d9969496d",
"release": "my-aerospike",
"statefulset.kubernetes.io/pod-name": "my-aerospike-0"
},
"name": "my-aerospike-0",
"namespace": "default",
"ownerReferences": [
{
"apiVersion": "apps/v1",
"blockOwnerDeletion": true,
"controller": true,
"kind": "StatefulSet",
"name": "my-aerospike",
"uid": "0b00ea3d-3b92-11ea-935e-025000000001"
}
],
"resourceVersion": "95058",
"selfLink": "/api/v2/namespaces/default/pods/my-aerospike-0",
"uid": "0b055519-3b92-11ea-935e-025000000001"
},
"spec": {
"containers": [
{
"image": "aerospike/aerospike-server:4.5.0.5",
"imagePullPolicy": "IfNotPresent",
"name": "my-aerospike",
"ports": [
{
"containerPort": 3000,
"name": "clients",
"protocol": "TCP"
},
{
"containerPort": 3002,
"name": "mesh",
"protocol": "TCP"
},
{
"containerPort": 3003,
"name": "info",
"protocol": "TCP"
}
],
"readinessProbe": {
"failureThreshold": 3,
"initialDelaySeconds": 15,
"periodSeconds": 10,
"successThreshold": 1,
"tcpSocket": {
"port": 3000
},
"timeoutSeconds": 1
},
"resources": {},
"terminationMessagePath": "/dev/termination-log",
"terminationMessagePolicy": "File",
"volumeMounts": [
{
"mountPath": "/etc/aerospike",
"name": "config-volume"
},
{
"mountPath": "/var/run/secrets/kubernetes.io/serviceaccount",
"name": "default-token-64jnc",
"readOnly": true
}
]
}
],
"dnsPolicy": "ClusterFirst",
"enableServiceLinks": true,
"hostname": "my-aerospike-0",
"nodeName": "docker-desktop",
"priority": 0,
"restartPolicy": "Always",
"schedulerName": "default-scheduler",
"securityContext": {},
"serviceAccount": "default",
"serviceAccountName": "default",
"subdomain": "my-aerospike",
"terminationGracePeriodSeconds": 30,
"tolerations": [
{
"effect": "NoExecute",
"key": "node.kubernetes.io/not-ready",
"operator": "Exists",
"tolerationSeconds": 300
},
{
"effect": "NoExecute",
"key": "node.kubernetes.io/unreachable",
"operator": "Exists",
"tolerationSeconds": 300
}
],
"volumes": [
{
"configMap": {
"defaultMode": 420,
"items": [
{
"key": "aerospike.conf",
"path": "aerospike.conf"
}
],
"name": "my-aerospike"
},
"name": "config-volume"
},
{
"name": "default-token-64jnc",
"secret": {
"defaultMode": 420,
"secretName": "default-token-64jnc"
}
}
]
},
"status": {
"conditions": [
{
"lastTransitionTime": "2020-01-20T09:35:02.000-05:00",
"status": "True",
"type": "Initialized"
},
{
"lastTransitionTime": "2020-01-21T15:05:33.000-05:00",
"status": "True",
"type": "Ready"
},
{
"lastTransitionTime": "2020-01-21T15:05:33.000-05:00",
"status": "True",
"type": "ContainersReady"
},
{
"lastTransitionTime": "2020-01-20T09:35:02.000-05:00",
"status": "True",
"type": "PodScheduled"
}
],
"containerStatuses": [
{
"containerID": "docker://b45436d2978cb8e6186b22c24d3b819cabd00921a009b30c2599a935d0c69b49",
"image": "aerospike/aerospike-server:4.5.0.5",
"imageID": "docker-pullable://aerospike/aerospike-server@sha256:5bec98d46c8a521003e1c5b6f015713f2663384dd66916cca696e4e1c142c539",
"lastState": {
"terminated": {
"containerID": "docker://5e4b23c07269669f302c7c6a446399e59d553cf1a622094c1d3cc64b6f65a9e0",
"exitCode": 255,
"finishedAt": "2020-01-21T15:04:35.000-05:00",
"reason": "Error",
"startedAt": "2020-01-20T10:28:19.000-05:00"
}
},
"name": "my-aerospike",
"ready": true,
"restartCount": 2,
"state": {
"running": {
"startedAt": "2020-01-21T15:05:16.000-05:00"
}
}
}
],
"hostIP": "192.168.65.3",
"phase": "Running",
"podIP": "10.1.0.129",
"qosClass": "BestEffort",
"startTime": "2020-01-20T09:35:02.000-05:00"
}
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/pods?cluster_id=:cluster_id
Retrieve a list of all pods in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the pods. |
| Attributes | |
|---|---|
id string |
The id of the pod. |
metadata object |
The metadata of the pod. |
metadata.annotations map |
The annotations of the pod. |
metadata.creationTimestamp string |
The date of creation of the pod as a string. |
metadata.labels map |
The labels associated to the pod. |
metadata.name string |
The name of the pod. |
metadata.namespace string |
The namespace in which the pod is created. |
metadata.uid object |
The UUID of the pod. |
specobject |
The specification used to create and run the pod. |
spec.containerstring |
The name of the container running. |
statusobject |
The status information of the pod. |
status.phasestring |
The status of the pod. Possible statuses are Running, Pending, Succeeded, Unknown and Failed. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a pod
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/pods/my-aerospike-0/default?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "my-aerospike-0/default",
"metadata": {
"annotations": {
"checksum/config": "0e07919467cc16f2c07ac99d0036405deafa06f7d3b430215915470b3a6ca631"
},
"creationTimestamp": "2020-01-20T09:35:02.000-05:00",
"generateName": "my-aerospike-",
"labels": {
"app": "aerospike",
"controller-revision-hash": "my-aerospike-d9969496d",
"release": "my-aerospike",
"statefulset.kubernetes.io/pod-name": "my-aerospike-0"
},
"name": "my-aerospike-0",
"namespace": "default",
"ownerReferences": [
{
"apiVersion": "apps/v1",
"blockOwnerDeletion": true,
"controller": true,
"kind": "StatefulSet",
"name": "my-aerospike",
"uid": "0b00ea3d-3b92-11ea-935e-025000000001"
}
],
"resourceVersion": "95058",
"selfLink": "/api/v2/namespaces/default/pods/my-aerospike-0",
"uid": "0b055519-3b92-11ea-935e-025000000001"
},
"spec": {
"containers": [
{
"image": "aerospike/aerospike-server:4.5.0.5",
"imagePullPolicy": "IfNotPresent",
"name": "my-aerospike",
"ports": [
{
"containerPort": 3000,
"name": "clients",
"protocol": "TCP"
},
{
"containerPort": 3002,
"name": "mesh",
"protocol": "TCP"
},
{
"containerPort": 3003,
"name": "info",
"protocol": "TCP"
}
],
"readinessProbe": {
"failureThreshold": 3,
"initialDelaySeconds": 15,
"periodSeconds": 10,
"successThreshold": 1,
"tcpSocket": {
"port": 3000
},
"timeoutSeconds": 1
},
"resources": {},
"terminationMessagePath": "/dev/termination-log",
"terminationMessagePolicy": "File",
"volumeMounts": [
{
"mountPath": "/etc/aerospike",
"name": "config-volume"
},
{
"mountPath": "/var/run/secrets/kubernetes.io/serviceaccount",
"name": "default-token-64jnc",
"readOnly": true
}
]
}
],
"dnsPolicy": "ClusterFirst",
"enableServiceLinks": true,
"hostname": "my-aerospike-0",
"nodeName": "docker-desktop",
"priority": 0,
"restartPolicy": "Always",
"schedulerName": "default-scheduler",
"securityContext": {},
"serviceAccount": "default",
"serviceAccountName": "default",
"subdomain": "my-aerospike",
"terminationGracePeriodSeconds": 30,
"tolerations": [
{
"effect": "NoExecute",
"key": "node.kubernetes.io/not-ready",
"operator": "Exists",
"tolerationSeconds": 300
},
{
"effect": "NoExecute",
"key": "node.kubernetes.io/unreachable",
"operator": "Exists",
"tolerationSeconds": 300
}
],
"volumes": [
{
"configMap": {
"defaultMode": 420,
"items": [
{
"key": "aerospike.conf",
"path": "aerospike.conf"
}
],
"name": "my-aerospike"
},
"name": "config-volume"
},
{
"name": "default-token-64jnc",
"secret": {
"defaultMode": 420,
"secretName": "default-token-64jnc"
}
}
]
},
"status": {
"conditions": [
{
"lastTransitionTime": "2020-01-20T09:35:02.000-05:00",
"status": "True",
"type": "Initialized"
},
{
"lastTransitionTime": "2020-01-21T15:05:33.000-05:00",
"status": "True",
"type": "Ready"
},
{
"lastTransitionTime": "2020-01-21T15:05:33.000-05:00",
"status": "True",
"type": "ContainersReady"
},
{
"lastTransitionTime": "2020-01-20T09:35:02.000-05:00",
"status": "True",
"type": "PodScheduled"
}
],
"containerStatuses": [
{
"containerID": "docker://b45436d2978cb8e6186b22c24d3b819cabd00921a009b30c2599a935d0c69b49",
"image": "aerospike/aerospike-server:4.5.0.5",
"imageID": "docker-pullable://aerospike/aerospike-server@sha256:5bec98d46c8a521003e1c5b6f015713f2663384dd66916cca696e4e1c142c539",
"lastState": {
"terminated": {
"containerID": "docker://5e4b23c07269669f302c7c6a446399e59d553cf1a622094c1d3cc64b6f65a9e0",
"exitCode": 255,
"finishedAt": "2020-01-21T15:04:35.000-05:00",
"reason": "Error",
"startedAt": "2020-01-20T10:28:19.000-05:00"
}
},
"name": "my-aerospike",
"ready": true,
"restartCount": 2,
"state": {
"running": {
"startedAt": "2020-01-21T15:05:16.000-05:00"
}
}
}
],
"hostIP": "192.168.65.3",
"phase": "Running",
"podIP": "10.1.0.129",
"qosClass": "BestEffort",
"startTime": "2020-01-20T09:35:02.000-05:00"
}
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/pods/:id?cluster_id=:cluster_id
Retrieve a pod and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the pod. |
| Attributes | |
|---|---|
id string |
The id of the pod. |
metadata object |
The metadata of the pod. |
metadata.annotations map |
The annotations of the pod. |
metadata.creationTimestamp string |
The date of creation of the pod as a string. |
metadata.labels map |
The labels associated to the pod. |
metadata.name string |
The name of the pod. |
metadata.namespace string |
The namespace in which the pod is created. |
metadata.uid object |
The UUID of the pod. |
specobject |
The specification used to create and run the pod. |
spec.containerstring |
The name of the container running. |
statusobject |
The status information of the pod. |
status.phasestring |
The status of the pod. Possible statuses are Running, Pending, Succeeded, Unknown and Failed. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a pod
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/pods"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Pod",
"metadata": {
"name": "edgar-allen-pod",
"namespace": "default"
},
"spec": {
"containers": [
{
"image": "nginx",
"name": "nginx"
}
]
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/pods
Create a pod in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the pod |
metadata object |
The metadata of the pod |
metadata.name string |
The name of the pod |
specobject |
The specification used to create and run the pod |
spec.container.imagestring |
The docker image name |
spec.container.namestring |
The (unique) name of the container specified as a DNS_LABEL |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the pod is created |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create pod task. |
taskStatus string |
The status of the operation. |
Replace a pod
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/pods/edgar-allen-pod/default"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Pod",
"metadata": {
"name": "edgar-allen-pod",
"namespace": "default"
},
"spec": {
"containers": [
{
"image": "nginx",
"name": "nginx"
}
]
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/pods/:id
Replace a pod in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the pod. |
metadata object |
The metadata of the pod. |
metadata.name string |
The name of the pod. |
specobject |
The specification used to replace and run the pod. |
spec.container.imagestring |
The docker image name. |
spec.container.namestring |
The (unique) name of the container specified as a DNS_LABEL. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the pod is replaced. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace pod task. |
taskStatus string |
The status of the operation. |
Delete a pod
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/pods/my-aerospike-0/default?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/pods/:id?cluster_id=:cluster_id
Delete a pod from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to delete the pod. |
| Attributes | |
|---|---|
taskId string |
The task id related to the delete pod task. |
taskStatus string |
The status of the operation. |
Deployments
List deployments
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/deployments?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "coredns/kube-system",
"deploymentStatus": "Progressing",
"readyRatio": "2/2",
"metadata": {},
"spec": {},
"status": {}
}
],
"metadata": {
"recordCount": 6
}
}
GET /services/:service_code/:environment_name/deployments?cluster_id=:cluster_id
Retrieve a list of all deployments in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the deployments. |
| Attributes | |
|---|---|
id string |
The id of the deployment |
metadata object |
The metadata of the deployment |
images object |
The container images within a deployment |
specobject |
The specification used to create and run the deployment |
readyRatio object |
The ready replicas to total replicas ratio of this deployment set |
deploymentStatusobject |
The status information of the deployment |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a deployment
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/deployments/coredns/kube-system?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "coredns/kube-system",
"deploymentStatus": "Progressing",
"readyRatio": "2/2",
"apiVersion": "apps/v1",
"kind": "Deployment",
"metadata": {},
"spec": {},
"status": {}
}
}
GET /services/:service_code/:environment_name/deployments/:id?cluster_id=:cluster_id
Retrieve a deployment and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the deployment. |
| Attributes | |
|---|---|
id string |
The id of the deployment |
metadata object |
The metadata of the deployment |
images object |
The container images within a deployment |
specobject |
The specification used to create and run the deployment |
readyRatio object |
The ready replicas to total replicas ratio of this deployment set |
deploymentStatusobject |
The status information of the deployment |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a deployment
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/deployments?cluster_id=a_cluster_id"
Content-Type: application/json
{
"apiVersion": "apps/v1",
"kind": "Deployment",
"metadata": {
"name": "api-test-deployment-name",
"namespace": "default"
},
"spec": {
"selector": {
"matchLabels": {
"app": "nginx"
}
},
"template": {
"metadata": {
"labels": {
"app": "nginx"
}
},
"spec": {
"containers": [
{
"name": "nginx",
"image": "nginx"
}
]
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/deployments?cluster_id=:cluster_id
Create a deployment in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the deployment. |
metadata object |
The metadata of the deployment. |
metadata.name string |
The name of the deployment. |
specobject |
The specification used to replace and run the deployment. |
spec.selectorobject |
The label query over the deployment's set of resources. |
spec.templateobject |
The data a deployment's pod should have when replaced. |
spec.specobject |
The specification used to replace and run the pod(s) within the deployment. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the deployment is replaced. |
spec.selector.matchLabelsobject |
The key value pairs retrieved by a label query from a deployment. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace deployment task. |
taskStatus string |
The status of the operation. |
Replace a deployment
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/deployments/deployment-name/default"
Content-Type: application/json
{
"apiVersion": "apps/v1",
"kind": "Deployment",
"metadata": {
"name": "deployment-name",
"namespace": "default"
},
"spec": {
"selector": {
"matchLabels": {
"app": "nginx"
}
},
"template": {
"metadata": {
"labels": {
"app": "nginx"
}
},
"spec": {
"containers": [
{
"name": "nginx",
"image": "nginx"
}
]
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/deployments/:id
Replace a deployment in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the deployment. |
metadata object |
The metadata of the deployment. |
metadata.name string |
The name of the deployment. |
specobject |
The specification used to create and run the deployment. |
spec.selectorobject |
The label query over the deployment's set of resources. |
spec.templateobject |
The data a deployment's pod should have when created. |
spec.specobject |
The specification used to create and run the pod(s) within the deployment. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the deployment is created. |
spec.selector.matchLabelsobject |
The key value pairs retrieved by a label query from a deployment. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create deployment task. |
taskStatus string |
The status of the operation. |
Delete a deployment
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/deployments/dex/auth?cluster_id=a_cluster_id?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/deployments/:id?cluster_id=:cluster_id
Delete a deployment from a given environment.
| Required Attributes | |
|---|---|
cluster_id string |
The id of the cluster in which to list the deployments. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete deployment task. |
taskStatus string |
The status of the operation. |
Daemon Sets
List daemon sets
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/daemonsets?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "kube-proxy/kube-system",
"readyRatio": "3/3",
"metadata": {},
"spec": {},
"status": {}
}
],
"metadata": {
"recordCount": 5
}
}
GET /services/:service_code/:environment_name/daemonsets?cluster_id=:cluster_id
Retrieve a list of all daemon sets in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the daemon sets. |
| Attributes | |
|---|---|
id string |
The id of the daemon set |
metadata object |
The metadata of the daemon set |
specobject |
The specification used to create and run the daemon set |
statusobject |
The status information of the daemon set |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a daemon set
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/daemonsets/test-aerospike/auth?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "kube-proxy/kube-system",
"readyRatio": "3/3",
"apiVersion": "apps/v1",
"kind": "DaemonSet",
"metadata": {},
"spec": {},
"status": {}
}
}
GET /services/:service_code/:environment_name/daemonsets/:id?cluster_id=:cluster_id
Retrieve a daemon set and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the daemon set. |
| Attributes | |
|---|---|
id string |
The id of the daemon set |
metadata object |
The metadata of the daemon set |
specobject |
The specification used to create and run the daemon set |
statusobject |
The status information of the daemon set |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a daemon set
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/daemonsets?cluster_id=a_cluster_id"
Content-Type: application/json
{
"apiVersion": "apps/v1",
"metadata": {
"name": "daemonset-name",
"namespace": "default"
},
"spec": {
"selector": {
"matchLabels": {
"name": "fluentd-elasticsearch"
}
},
"template": {
"metadata": {
"labels": {
"name": "fluentd-elasticsearch"
}
},
"spec": {
"containers": [
{
"name": "fluentd-elasticsearch",
"image": "quay.io/fluentd_elasticsearch/fluentd:v2.5.2"
}
]
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/daemonsets?cluster_id=:cluster_id
Create a daemon set in a given environment.
| Required Attributes | |
|---|---|
cluster_id string |
The id of the cluster in which to get the daemon set. |
apiVersion string |
The api version (versioned schema) of the daemon set |
metadata object |
The metadata of the daemon set |
metadata.name string |
The name of the daemon set |
specobject |
The specification used to create and run the daemon set |
spec.selectorobject |
The label query over the daemon set's resources |
spec.templateobject |
The data a daemon set's pod should have when created |
spec.specobject |
The specification used to create and run the pod(s) within the daemon set |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the daemon set is created |
spec.selector.matchLabelsobject |
The key value pairs retrieved by a label query from a daemon set |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create daemon set task. |
taskStatus string |
The status of the operation. |
Replace a daemon set
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/daemonsets/daemonset-name/default"
Content-Type: application/json
{
"apiVersion": "apps/v1",
"kind": "DaemonSet",
"metadata": {
"name": "daemonset-name",
"namespace": "default"
},
"spec": {
"selector": {
"matchLabels": {
"name": "fluentd-elasticsearch"
}
},
"template": {
"metadata": {
"labels": {
"name": "fluentd-elasticsearch"
}
},
"spec": {
"containers": [
{
"name": "fluentd-elasticsearch",
"image": "quay.io/fluentd_elasticsearch/fluentd:v2.5.2"
}
]
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/daemonsets/:id
Replace a daemon set in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the daemon set. |
metadata object |
The metadata of the daemon set. |
metadata.name string |
The name of the daemon set. |
specobject |
The specification used to replace and run the daemon set. |
spec.selectorobject |
The label query over the daemon set's resources. |
spec.templateobject |
The data a daemon set's pod should have when replaced. |
spec.specobject |
The specification used to create and run the pod(s) within the daemon set. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the daemon set is replaced. |
spec.selector.matchLabelsobject |
The key value pairs retrieved by a label query from a daemon set. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace daemon set task. |
taskStatus string |
The status of the operation. |
Delete a daemon set
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/daemonsets/nginx-ingress-controller/ingress-nginx?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/daemonsets/:id?cluster_id=:cluster_id
Delete a daemon set from a given environment.
| Required Attributes | |
|---|---|
cluster_id string |
The id of the cluster in which to get the daemon set. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete daemon set task. |
taskStatus string |
The status of the operation. |
Stateful Sets
List stateful sets
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/statefulsets?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "test-aerospike/auth",
"images": ["aerospike/aerospike-server:4.5.0.5"],
"metadata": {},
"spec": {},
"status": {}
}
],
"metadata": {
"recordCount": 4
}
}
GET /services/:service_code/:environment_name/statefulsets?cluster_id=:cluster_id
Retrieve a list of all stateful sets in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the stateful sets. |
| Attributes | |
|---|---|
id string |
The id of the stateful set |
metadata object |
The metadata of the stateful set |
specobject |
The specification used to create and run the stateful set |
statusobject |
The status information of the stateful set |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a stateful set
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/statefulsets/test-aerospike/auth?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "test-aerospike/auth",
"replicaRatio": "1 / 1",
"images": ["aerospike/aerospike-server:4.5.0.5"],
"apiVersion": "apps/v1",
"kind": "StatefulSet",
"metadata": {},
"spec": {},
"status": {}
}
}
GET /services/:service_code/:environment_name/statefulsets/:id?cluster_id=:cluster_id
Retrieve a stateful set and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the stateful set. |
| Attributes | |
|---|---|
id string |
The id of the stateful set |
metadata object |
The metadata of the stateful set |
specobject |
The specification used to create and run the stateful set |
statusobject |
The status information of the stateful set |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a stateful set
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/statefulsets?cluster_id=a_cluster_id"
Content-Type: application/json
{
"apiVersion": "apps/v1",
"kind":"StatefulSet",
"metadata": {
"name": "stateful-set-name",
"namespace": "default"
},
"spec": {
"selector": {
"matchLabels": {
"app": "nginx"
}
},
"template": {
"metadata": {
"labels": {
"app": "nginx"
}
},
"spec": {
"containers": [
{
"name": "nginx",
"image": "k8s.gcr.io/nginx-slim:0.8"
}
]
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/statefulsets?cluster_id=:cluster_id
Create a stateful set in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the stateful set |
metadata object |
The metadata of the stateful set |
metadata.name string |
The name of the stateful set |
specobject |
The specification used to create and run the stateful set |
spec.selectorobject |
The label query over the stateful set's resources |
spec.templateobject |
The data a stateful set's pod should have when created |
spec.specobject |
The specification used to create and run the pod(s) within the stateful set |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the stateful set is created |
spec.selector.matchLabelsobject |
The key value pairs retrieved by a label query from a stateful set |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create stateful set task. |
taskStatus string |
The status of the operation. |
Replace a stateful set
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/statefulsets/stateful-set-name/default"
Content-Type: application/json
{
"apiVersion": "apps/v1",
"kind": "StatefulSet",
"metadata": {
"name": "stateful-set-name",
"namespace": "default"
},
"spec": {
"selector": {
"matchLabels": {
"app": "nginx"
}
},
"template": {
"metadata": {
"labels": {
"app": "nginx"
}
},
"spec": {
"containers": [
{
"name": "nginx",
"image": "k8s.gcr.io/nginx-slim:0.8"
}
]
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/statefulsets/:id
Replace a stateful set in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the stateful set. |
metadata object |
The metadata of the stateful set. |
metadata.name string |
The name of the stateful set. |
specobject |
The specification used to replaced and run the stateful set. |
spec.selectorobject |
The label query over the stateful set's of resources. |
spec.templateobject |
The data a stateful set's pod should have when replaced. |
spec.specobject |
The specification used to replace and run the pod(s) within the stateful set. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the stateful set is replaced. |
spec.selector.matchLabelsobject |
The key value pairs retrieved by a label query from a stateful set. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace stateful set task. |
taskStatus string |
The status of the operation. |
Delete a stateful set
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/statefulsets/my-aerospike/default"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/statefulsets/:id?cluster_id=:cluster_id
Delete a stateful set from a given environment.
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete stateful set task. |
taskStatus string |
The status of the operation. |
Networking (k8s)
Services
List services
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/services?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "alaintest-aerospike/default",
"ports": ["3000/TCP", "3002/TCP"],
"type": "ClusterIP",
"metadata": {},
"spec": {},
"status": {
"loadBalancer": {}
}
},
{
"id": "alertmanager-operated/monitoring",
"ports": ["9093/TCP", "9094/TCP", "9094/UDP"],
"type": "NodePort",
"apiVersion": "v1",
"kind": "Service",
"metadata": {},
"spec": {},
"status": {
"loadBalancer": {}
}
}
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/services?cluster_id=:cluster_id
Retrieve a list of all services in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the service. |
| Attributes | |
|---|---|
id string |
The id of the service |
metadata object |
The metadata of the service |
metadata.name string |
The name of the service |
metadata.namespace string |
The namespace in which the service is created |
metadata.uid object |
The UUID of the service |
type object |
The container images within a service |
portsobject |
The list of ports that are exposed by this service |
specobject |
The attributes that a user creates on a service |
spec.selectorobject |
The keys and values corresponding to pod labels, used to determine where service traffic will be routed |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a service
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/services/test-aerospike/auth?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "test-aerospike/auth",
"ports": ["3000/TCP", "3002/TCP"],
"type": "ClusterIP",
"apiVersion": "v1",
"kind": "Service",
"metadata": {},
"spec": {},
"status": {
"loadBalancer": {}
}
}
}
GET /services/:service_code/:environment_name/services/:id?cluster_id=:cluster_id
Retrieve a service and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the service. |
| Attributes | |
|---|---|
id string |
The id of the service |
metadata object |
The metadata of the service |
metadata.name string |
The name of the service |
metadata.namespace string |
The namespace in which the service is created |
metadata.uid object |
The UUID of the service |
type object |
The container images within a service |
portsobject |
The list of ports that are exposed by this service |
specobject |
The attributes that a user creates on a service |
spec.selectorobject |
The keys and values corresponding to pod labels, used to determine where service traffic will be routed |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a service
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/services"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Service",
"metadata": {
"name": "service-name",
"namespace": "default"
},
"spec": {
"ports": [
{
"port": 3000,
"protocol": "TCP"
}
],
"type": "ClusterIP"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/services/:id?cluster_id=:cluster_id
Create a service in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the service. |
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the service. |
metadata object |
The metadata of the service. |
metadata.name string |
The name of the service. |
specobject |
The specification used to create and run the service. |
spec.selectorobject |
The label query over the service's set of resources. |
spec.portsobject |
The list of ports that are exposed by this service. |
spec.typeobject |
The type of service (ClusterIP, NodePort, ExternalName or LoadBalancer) |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the service is created. |
spec.selector.matchLabelsobject |
The key value pairs retrieved by a label query from a service. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create service task. |
taskStatus string |
The status of the operation. |
Replace a service
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/services/service-name/default?cluster_id=test-cluster"
Request body example:
{
"type": "LoadBalancer",
"ports": [
"4000/TCP"
],
"apiVersion": "v1",
"kind": "Service",
"metadata": {
"creationTimestamp": "2020-08-13T11:05:00.000-04:00",
"name": "service-name",
"namespace": "default",
"resourceVersion": "170742452",
"selfLink": "/api/v2/namespaces/default/services/service-name",
"uid": "a84c8fea-f9d9-47ab-8e58-37059e9f18bd"
},
"spec": {
"clusterIP": "10.245.44.45",
"externalTrafficPolicy": "Cluster",
"ports": [
{
"nodePort": 31167,
"port": 3000,
"protocol": "TCP",
"targetPort": 306
}
],
"sessionAffinity": "ClientIP",
"sessionAffinityConfig": {
"clientIP": {
"timeoutSeconds": 10555
}
},
"type": "LoadBalancer"
},
"status": {
"loadBalancer": {}
}
}
PUT /services/:service_code/:environment_name/services/:id?cluster_id=:cluster_id
Replace a service in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the service. |
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the service. |
metadata object |
The metadata of the service. |
metadata.name string |
The name of the service. |
specobject |
The specification used to create and run the service. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace service task. |
taskStatus string |
The status of the operation. |
Delete a service
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/services/test-service/default?cluster_id=test-cluster"
DELETE /services/:service_code/:environment_name/services/:id?cluster_id=:cluster_id
Delete a service from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the service. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete service task. |
taskStatus string |
The status of the operation. |
Ingresses V1Beta1
Ingress v1beta1 has been deprecated in this API as of 26.7.0 following the removal of support by kubernetes. Please use the ingress v1 api instead.
Ingresses V1
List ingresses V1
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/ingressesv1?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "cloudmc/cmc-stg",
"endpoint": "http://cmc.cloudmc-staging-endpoint.com",
"service": {
"port": "8080",
"name": "cloudmc"
},
"metadata": {
"annotations": {},
"creationTimestamp": "2019-07-11T10:00:18.000-04:00",
"generation": 10,
"name": "cloudmc",
"namespace": "cmc-stg",
"resourceVersion": "143213903",
"uid": "376bc4c5-a3e4-11e9-b6bd-02006e76001e"
},
"spec": {
"rules": [],
"tls": []
},
"status": {
"loadBalancer": {}
}
},
{
"id": "cm-acme-http-solver-75png/auth",
"endpoint": "http://cmc.cloudmc-staging-endpoint.com",
"service": {
"port": "8089",
"name": "cm-acme-http-solver-2x5gv"
},
"metadata": {
"annotations": {},
"creationTimestamp": "2020-06-24T11:00:49.000-04:00",
"generateName": "cm-acme-http-solver-",
"generation": 1,
"labels": {
"acme.cert-manager.io/http-domain": "1965164889",
"acme.cert-manager.io/http-token": "820448657",
"acme.cert-manager.io/http01-solver": "true"
},
"name": "cm-acme-http-solver-75png",
"namespace": "auth",
"ownerReferences": [],
"resourceVersion": "143213968",
"uid": "48720f48-f2bc-45fc-95c5-60cae8ffe11e"
},
"spec": {
"rules": []
},
"status": {
"loadBalancer": {}
}
}
]
}
GET /services/:service_code/:environment_name/ingressesv1?cluster_id=:cluster_id
Retrieve a list of all ingresses V1 in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the ingress. |
| Attributes | |
|---|---|
id string |
The id of the ingress |
endpoint string |
The endpoint of the ingress |
service object |
The service associated with the ingress |
service.port string |
The port of the service associated with the ingress |
service.name string |
The name of the service associated with the ingress |
metadata object |
The metadata of the ingress |
metadata.name string |
The name of the ingress |
metadata.namespace string |
The namespace in which the ingress is created |
metadata.labels object |
The labels associated with the ingress |
metadata.uid object |
The UUID of the ingress |
specobject |
The attributes that a user specifies for an ingress |
Note that the list is not complete, since it is referring to the kubernetes api details.
Get an ingress V1
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/ingressesv1/cloudmc/cmc-stg?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "cloudmc/cmc-stg",
"endpoint": "http://cmc.cloudmc-staging-endpoint.com",
"service": {
"port": "8080",
"name": "cloudmc"
},
"metadata": {
"annotations": {},
"creationTimestamp": "2019-07-11T10:00:18.000-04:00",
"generation": 10,
"name": "cloudmc",
"namespace": "cmc-stg",
"resourceVersion": "143213903",
"uid": "376bc4c5-a3e4-11e9-b6bd-02006e76001e"
},
"spec": {
"rules": [],
"tls": []
},
"status": {
"loadBalancer": {}
}
}
}
GET /services/:service_code/:environment_name/ingressesv1/:id?cluster_id=:cluster_id
Retrieve an ingress V1 and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the ingress. |
| Attributes | |
|---|---|
id string |
The id of the ingress |
endpoint string |
The endpoint of the ingress |
service object |
The service associated with the ingress |
service.port string |
The port of the service associated with the ingress |
service.name string |
The name of the service associated with the ingress |
metadata object |
The metadata of the ingress |
metadata.name string |
The name of the ingress |
metadata.namespace string |
The namespace in which the ingress is created |
metadata.labels object |
The labels associated with the ingress |
metadata.uid object |
The UUID of the ingress |
specobject |
The attributes that a user specifies for an ingress |
Note that the list is not complete, since it is referring to the kubernetes api details.
Create an ingress V1
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/ingressesv1"
Content-Type: application/json
{
"apiVersion": "networking.k8s.io/v1",
"kind": "Ingress",
"metadata": {
"name": "ingress-name",
"namespace": "default",
"annotations": {
"nginx.ingress.kubernetes.io/rewrite-target": "/"
}
},
"spec": {
"rules": [
{
"hostname": "endpoint.com",
"http": {
"paths": [
{
"path": "/testpath",
"pathType": "Prefix",
"backend": {
"service": {
"name": "test",
"port": {
"number": 80
}
}
}
}
]
}
}
]
}
}
POST /services/:service_code/:environment_name/ingressesv1/:id?cluster_id=:cluster_id
Create an ingress V1 in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the ingress. |
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the ingress. |
metadata object |
The metadata of the ingress. |
metadata.name string |
The name of the ingress. |
specobject |
The specification used to create and run the ingress. |
spec.rulesobject |
The list of host rules used to configure the ingress. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the ingress is created. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create ingress task. |
taskStatus string |
The status of the operation. |
Replace an ingress V1
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/ingressesv1/ingress-name/default?cluster_id=test-cluster"
Request body example:
{
"endpoint": "http://my-endpoint.com",
"service": {
"port": "6556",
"name": "test"
},
"apiVersion": "networking.k8s.io/v1",
"kind": "Ingress",
"metadata": {
"creationTimestamp": "2020-08-13T14:13:42.000-04:00",
"generation": 3,
"name": "ingress-name",
"namespace": "default",
"resourceVersion": "170302224",
"uid": "c67e6a6a-2b07-4976-8b3d-2ec9fd91ae5d"
},
"spec": {
"rules": [
{
"host": "my-endpoint.com",
"http": {
"paths": [
{
"backend": {
"service": {
"name": "test",
"port": {
"number": 6556
}
}
},
"path": "/testpath"
}
]
}
}
]
},
"status": {
"loadBalancer": {
"ingress": [
{
"hostname": "hostname-worker-01"
},
{
"hostname": "hostname-worker-02"
},
{
"hostname": "hostname-worker-03"
},
{
"hostname": "hostname-worker-04"
}
]
}
}
}
PUT /services/:service_code/:environment_name/ingressesv1/:id?cluster_id=:cluster_id
Replace an ingress V1 in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the ingress. |
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the ingress. |
metadata object |
The metadata of the ingress. |
metadata.name string |
The name of the ingress. |
specobject |
The specification used to create and run the ingress. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace ingress task. |
taskStatus string |
The status of the operation. |
Delete an ingress V1
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/ingressesv1/test-ingress/default?cluster_id=test-cluster"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/ingressesv1/:id?cluster_id=:cluster_id
Delete an ingress V1 from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the ingress. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete ingress task. |
taskStatus string |
The status of the operation. |
Configuration
Config Maps
List config maps
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/configmaps?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "coredns/kube-system",
"data": {
"Corefile": ".:53 {\n errors\n health\n kubernetes cluster.local in-addr.arpa ip6.arpa {\n pods insecure\n upstream\n fallthrough in-addr.arpa ip6.arpa\n }\n prometheus :9153\n forward . /etc/resolv.conf\n cache 30\n loop\n reload\n loadbalance\n import custom/.override\n}\nimport custom/.server\n"
},
"metadata": {}
}
],
"metadata": {
"recordCount": 4
}
}
GET /services/:service_code/:environment_name/configmaps?cluster_id=:cluster_id
Retrieve a list of all config maps in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the config maps. |
| Attributes | |
|---|---|
id string |
The id of the config map. |
apiVersion string |
The API version used to retrieve this config map. |
metadata object |
The metadata of the config map. |
Get a config map
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/configmaps/coredns/kube-system?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "coredns/kube-system",
"apiVersion": "v1",
"data": {
"Corefile": ".:53 {\n errors\n health\n kubernetes cluster.local in-addr.arpa ip6.arpa {\n pods insecure\n upstream\n fallthrough in-addr.arpa ip6.arpa\n }\n prometheus :9153\n forward . /etc/resolv.conf\n cache 30\n loop\n reload\n loadbalance\n import custom/.override\n}\nimport custom/.server\n"
},
"kind": "ConfigMap",
"metadata": {}
}
}
GET /services/:service_code/:environment_name/configmaps/:id?cluster_id=:cluster_id
Retrieve a config map and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the config map. |
| Attributes | |
|---|---|
id string |
The id of the config map. |
apiVersion string |
The API version used to retrieve this config map. |
metadata object |
The metadata of the config map. |
Create a config map
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/configmaps?cluster_id=:cluster_id"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "ConfigMap",
"metadata": {
"name": "game-demo"
},
"data": {
"player_initial_lives": "3",
"ui_properties_file_name": "user-interface.properties",
"game.properties": "enemy.types=aliens,monsters\nplayer.maximum-lives=5\n",
"user-interface.properties": "color.good=purple\ncolor.bad=yellow\nallow.textmode=true\n"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/configmaps?cluster_id=:cluster_id
Create a config map in a given environment.
| Required Attributes | |
|---|---|
cluster_id string |
The id of the cluster in which to create the config map. |
apiVersion string |
The api version (versioned schema) of the config map. |
metadata object |
The metadata of the config map. |
metadata.name string |
The name of the config map. |
dataobject |
The non-confidential data (in key-value pairs) stored in the config map. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the config map is created |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create config maps task. |
taskStatus string |
The status of the operation. |
Replace a config map
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/configmaps/game-demo/default?cluster_id=:cluster_id"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "ConfigMap",
"metadata": {
"name": "game-demo",
"namespace": "default"
},
"data": {
"player_initial_lives": "5",
"ui_properties_file_name": "user-interface.properties",
"game.properties": "enemy.types=aliens,monsters\nplayer.maximum-lives=5\n",
"user-interface.properties": "color.good=purple\ncolor.bad=yellow\nallow.textmode=true\n"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/configmaps/:id?cluster_id=:cluster_id
Replace a config map in a given environment.
| Required Attributes | |
|---|---|
cluster_id string |
The id of the cluster in which to replace the config map. |
apiVersion string |
The api version (versioned schema) of the config map. |
metadata object |
The metadata of the config map. |
metadata.name string |
The name of the config map. |
dataobject |
The non-confidential data (in key-value pairs) stored in the config map. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the config map is replaced. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace config maps task. |
taskStatus string |
The status of the operation. |
Delete a config map
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/configmaps/cert-manager-cainjector-leader-election/kube-system?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/configmaps/:id?cluster_id=:cluster_id
Delete a config map from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to delete the config map. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete config map task. |
taskStatus string |
The status of the operation. |
Secrets
List secrets
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/secrets?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "default-token-xxxmt/default",
"apiVersion": "v1",
"encodedData": {
"ca.crt": "LS0tLS...",
"namespace": "a3ViZS1zeXN0ZW0=",
"token": "ZXlKa..."
},
"kind": "Secret",
"metadata": {},
"type": "kubernetes.io/service-account-token"
}
],
"metadata": {
"recordCount": 100
}
}
GET /services/:service_code/:environment_name/secrets?cluster_id=:cluster_id
Retrieve a list of all secrets in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the secrets. |
| Attributes | |
|---|---|
id string |
The id of the secret. |
apiVersion string |
The API version used to retrieve the secret. |
encodedDataobject |
The base64 encoded data stored in the secret. |
metadata object |
The metadata of the secret. |
type string |
A string used to facilitate programmatic handling of a secret's data. |
Get a secret
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/secrets/default-token-xxxmt/default?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "default-token-xxxmt/default",
"apiVersion": "v1",
"encodedData": {
"ca.crt": "LS0tLS...",
"namespace": "a3ViZS1zeXN0ZW0=",
"token": "ZXlKa..."
},
"kind": "Secret",
"metadata": {},
"type": "kubernetes.io/service-account-token"
}
}
GET /services/:service_code/:environment_name/secrets/:id?cluster_id=:cluster_id
Retrieve a secret and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the secret. |
| Attributes | |
|---|---|
id string |
The id of the secret. |
apiVersion string |
The API version used to retrieve the secret. |
encodedDataobject |
The base64 encoded data stored in the secret. |
metadata object |
The metadata of the secret. |
type string |
A string used to facilitate programmatic handling of a secret's data. |
Create a secret
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/secrets"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Secret",
"metadata": {
"name": "mysecret"
},
"type": "Opaque",
"stringData": {
"username": "my-username",
"password": "my-password"
}
}
# OR
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/secrets?cluster_id=:cluster_id"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Secret",
"metadata": {
"name": "mysecret"
},
"type": "Opaque",
"encodedData": {
"username": "YWRtaW4=",
"password": "MWYyZDFlMmU2N2Rm"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/secrets?cluster_id=:cluster_id
Create a secret in a given environment.
| Required Attributes | |
|---|---|
cluster_id string |
The id of the cluster in which to create the secret. |
apiVersion string |
The api version (versioned schema) of the secret. |
metadata object |
The metadata of the secret. |
metadata.name string |
The name of the secret. |
One of the following two attributes is also required.
| Attributes | |
|---|---|
encodedDataobject |
The base64 encoded data stored in the secret. |
stringDataobject |
The non-base64 encoded data to be encoded when the secret is created. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the secret is created |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create secret task. |
taskStatus string |
The status of the operation. |
Replace a secret
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/secrets/my-secret/shhh"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Secret",
"metadata": {
"name": "mysecret"
},
"type": "Opaque",
"stringData": {
"username": "my-username",
"password": "my-new-password"
}
}
# OR
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/secrets?cluster_id=:cluster_id"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Secret",
"metadata": {
"name": "mysecret",
"namespace": "shhh"
},
"type": "Opaque",
"encodedData": {
"username": "YWRtaW4=",
"password": "MWYyFZDlMmU2N2Rm"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/secrets/:id?cluster_id=:cluster_id
Replace a secret in a given environment.
| Required Attributes | |
|---|---|
cluster_id string |
The id of the cluster in which to replace the secret. |
apiVersion string |
The api version (versioned schema) of the secret. |
metadata object |
The metadata of the secret. |
metadata.name string |
The name of the secret. |
One of the following two attributes is also required.
| Attributes | |
|---|---|
encodedDataobject |
The base64 encoded data stored in the secret. |
stringDataobject |
The non-base64 encoded data to be encoded when the secret is replaced. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the secret is replaced |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace secret task. |
taskStatus string |
The status of the operation. |
Delete a secret
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/secrets/default-token-xxxmt/default?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/secrets/:id?cluster_id=:cluster_id
Delete a secret from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to delete the secret. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete secret task. |
taskStatus string |
The status of the operation. |
Storage (k8s)
Storage Classes
List storage classes
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/storageclasses?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "rook-ceph-block",
"isDefault": true,
"allowVolumeExpansion": true,
"metadata": {
"annotations": {
"storageclass.kubernetes.io/is-default-class": "true"
},
"creationTimestamp": "2020-04-20T16:08:54.000-04:00",
"name": "rook-ceph-block",
"resourceVersion": "107033002",
"selfLink": "/apis/storage.k8s.io/v1/storageclasses/rook-ceph-block",
"uid": "f289c0e6-3f20-4274-8cb8-5db8b34dece6"
},
"parameters": {
"clusterID": "rook-ceph",
"csi.storage.k8s.io/controller-expand-secret-name": "rook-csi-rbd-provisioner",
"csi.storage.k8s.io/controller-expand-secret-namespace": "rook-ceph",
"csi.storage.k8s.io/fstype": "ext4",
"csi.storage.k8s.io/node-stage-secret-name": "rook-csi-rbd-node",
"csi.storage.k8s.io/node-stage-secret-namespace": "rook-ceph",
"csi.storage.k8s.io/provisioner-secret-name": "rook-csi-rbd-provisioner",
"csi.storage.k8s.io/provisioner-secret-namespace": "rook-ceph",
"imageFeatures": "layering",
"imageFormat": "2",
"pool": "replicapool"
},
"provisioner": "rook-ceph.rbd.csi.ceph.com",
"reclaimPolicy": "Delete",
"volumeBindingMode": "Immediate"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/storageclasses?cluster_id=:cluster_id
Retrieve a list of all storage classes in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the storage classes. |
| Attributes | |
|---|---|
id string |
The id of the storage class. This is the name of the resource. |
isDefault boolean |
Whether or not the storage class is the default one. |
allowVolumeExpansion boolean |
Whether not the storage class allows for expandable volumes. |
metadata object |
The metadata of the storage class. |
parameters object |
The parameters for the storage provisioner. These are storage provisioner specific and you will likely have to read external documentation. |
provisioner string |
The provisioner for the storage class. |
reclaimPolicy string |
The default volume reclaim policy for this storage class. You have a choice between Reclaim or Delete. |
volumeBindingMode string |
The default volume binding model for this storage class. You have a choice between Immediate or WaitForFirstConsumer. |
Get a storage class
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/storageclasses/rook-ceph-block?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "rook-ceph-block",
"isDefault": true,
"allowVolumeExpansion": true,
"metadata": {
"annotations": {
"storageclass.kubernetes.io/is-default-class": "true"
},
"creationTimestamp": "2020-04-20T16:08:54.000-04:00",
"name": "rook-ceph-block",
"resourceVersion": "107033002",
"selfLink": "/apis/storage.k8s.io/v1/storageclasses/rook-ceph-block",
"uid": "f289c0e6-3f20-4274-8cb8-5db8b34dece6"
},
"parameters": {
"clusterID": "rook-ceph",
"csi.storage.k8s.io/controller-expand-secret-name": "rook-csi-rbd-provisioner",
"csi.storage.k8s.io/controller-expand-secret-namespace": "rook-ceph",
"csi.storage.k8s.io/fstype": "ext4",
"csi.storage.k8s.io/node-stage-secret-name": "rook-csi-rbd-node",
"csi.storage.k8s.io/node-stage-secret-namespace": "rook-ceph",
"csi.storage.k8s.io/provisioner-secret-name": "rook-csi-rbd-provisioner",
"csi.storage.k8s.io/provisioner-secret-namespace": "rook-ceph",
"imageFeatures": "layering",
"imageFormat": "2",
"pool": "replicapool"
},
"provisioner": "rook-ceph.rbd.csi.ceph.com",
"reclaimPolicy": "Delete",
"volumeBindingMode": "Immediate"
}
}
GET /services/:service_code/:environment_name/storageclasses/:id?cluster_id=:cluster_id
Retrieve a storage class and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the storage classes. |
| Attributes | |
|---|---|
id string |
The id of the storage class. This is the name of the resource |
isDefault boolean |
Whether or not the storage class is the default one |
allowVolumeExpansion boolean |
Whether not the storage class allows for expandable volumes. |
metadata object |
The metadata of the storage class. |
parameters object |
The parameters for the storage provisioner. These are storage provisioner specific and you will likely have to read external documentation. |
provisioner string |
The provisioner for the storage class |
reclaimPolicy string |
The default volume reclaim policy for this storage class. You have a choice between Reclaim or Delete. |
volumeBindingMode string |
The default volume binding model for this storage class. You have a choice between Immediate or WaitForFirstConsumer. |
Create a storage class
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/storageclasses?cluster_id=a_cluster_id"
Content-Type: application/json
{
"apiVersion": "storage.k8s.io/v1",
"kind": "StorageClass",
"metadata": {
"name": "local-storage-name"
},
"provisioner": "kubernetes.io/no-provisioner",
"volumeBindingMode": "WaitForFirstConsumer"
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/storageclasses?cluster_id=:cluster_id
Create a storage class in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the storage class. |
metadata object |
The metadata of the storage class. |
metadata.name string |
The name of the storage class. |
provisioner string |
The provisioner for the storage class |
volumeBindingMode string |
The default volume binding model for this storage class. You have a choice between Immediate or WaitForFirstConsumer. |
| Optional Attributes | |
|---|---|
reclaimPolicy string |
The default volume reclaim policy for this storage class. You have a choice between Reclaim or Delete. |
parameters object |
The parameters for the storage provisioner. These are storage provisioner specific and you will likely have to read external documentation. |
allowVolumeExpansion boolean |
Whether not the storage class allows for expandable volumes. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create stateful set task. |
taskStatus string |
The status of the operation. |
Replace a storage class
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/storageclasses/rook-ceph-block?cluster_id=a_cluster_id"
Content-Type: application/json
{
"apiVersion": "storage.k8s.io/v1",
"metadata": {
"name": "hostpath"
},
"provisioner": "docker.io/hostpath"
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/storageclasses/:id?cluster_id=:cluster_id
Replace a storage class in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the storage class. |
metadata object |
The metadata of the storage class. |
metadata.name string |
The name of the storage class. |
provisionerobject |
The type of provisioner. |
| Optional Attributes | |
|---|---|
reclaimPolicy string |
Dynamically provisioned PersistentVolumes of this storage class are created with this reclaimPolicy. Defaults to Delete. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace storage class task. |
taskStatus string |
The status of the operation. |
Delete a storage class
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/storageclasses/rook-ceph-block?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/storageclasses/:id?cluster_id=:cluster_id
Delete a storage class from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the storage class. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete storage class task. |
taskStatus string |
The status of the operation. |
Persistent volumes
List persistent volumes
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumes?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "pvc-05097a93-120d-45d2-aaab-0f273849fccd",
"metadata": {
"annotations": {
"pv.kubernetes.io/provisioned-by": "rook-ceph.rbd.csi.ceph.com"
},
"creationTimestamp": "2020-07-03T09:12:17.000-04:00",
"finalizers": ["kubernetes.io/pv-protection"],
"name": "pvc-05097a93-120d-45d2-aaab-0f273849fccd",
"resourceVersion": "147569183",
"selfLink": "/api/v2/persistentvolumes/pvc-05097a93-120d-45d2-aaab-0f273849fccd",
"uid": "2e20a8fb-d90c-4c39-acd8-7007f85e2d8e"
},
"spec": {
"accessModes": ["ReadWriteOnce"],
"capacity": {
"storage": "8Gi"
},
"claimRef": {
"apiVersion": "v1",
"kind": "PersistentVolumeClaim",
"name": "data-cmc-cluster-zookeeper-1",
"namespace": "cmc-kafka",
"resourceVersion": "147569124",
"uid": "05097a93-120d-45d2-aaab-0f273849fccd"
},
"csi": {
"driver": "rook-ceph.rbd.csi.ceph.com",
"fsType": "ext4",
"nodeStageSecretRef": {
"name": "rook-csi-rbd-node",
"namespace": "rook-ceph"
},
"volumeAttributes": {
"clusterID": "rook-ceph",
"imageFeatures": "layering",
"imageFormat": "2",
"pool": "replicapool",
"storage.kubernetes.io/csiProvisionerIdentity": "1593101040137-8081-rook-ceph.rbd.csi.ceph.com"
},
"volumeHandle": "0001-0009-rook-ceph-0000000000000001-d11d2a4d-bd2e-11ea-b56e-7a7db811cab1"
},
"persistentVolumeReclaimPolicy": "Delete",
"storageClassName": "rook-ceph-block",
"volumeMode": "Filesystem"
},
"status": {
"phase": "Bound"
}
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/persistentvolumes?cluster_id=:cluster_id
Retrieve a list of all persistent volumes in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the persistent volumes. |
| Attributes | |
|---|---|
id string |
The id of the persistent volume. This is the name of the resource. |
metadata object |
The metadata of the persistent volume. |
spec object |
The specification of the persistent volume. |
spec.accessModes string |
The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes). |
spec.capacity.storage string |
Storage capacity of the persistent volume. |
spec.persistentVolumeReclaimPolicy string |
One of Retain (manual reclamation), Recycle (basic scrub) or Delete (associated storage asset such as AWS EBS, GCE PD, Azure Disk, or OpenStack Cinder volume is deleted). |
spec.storageClassName string |
Storage class associated to the volume. |
spec.capacity.volumeMode string |
If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device. |
status.phase string |
Volume is in one of the following phases: Available, Bound, Released or Failed. |
Get a persistent volume
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumes/pvc-05097a93-120d-45d2?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"id": "pvc-05097a93-120d-45d2",
"metadata": {
"annotations": {
"pv.kubernetes.io/provisioned-by": "rook-ceph.rbd.csi.ceph.com"
},
"creationTimestamp": "2020-07-03T09:12:17.000-04:00",
"finalizers": ["kubernetes.io/pv-protection"],
"name": "pvc-05097a93-120d-45d2-aaab-0f273849fccd",
"resourceVersion": "147569183",
"selfLink": "/api/v2/persistentvolumes/pvc-05097a93-120d-45d2-aaab-0f273849fccd",
"uid": "2e20a8fb-d90c-4c39-acd8-7007f85e2d8e"
},
"spec": {
"accessModes": ["ReadWriteOnce"],
"capacity": {
"storage": "8Gi"
},
"claimRef": {
"apiVersion": "v1",
"kind": "PersistentVolumeClaim",
"name": "data-cmc-cluster-zookeeper-1",
"namespace": "cmc-kafka",
"resourceVersion": "147569124",
"uid": "05097a93-120d-45d2-aaab-0f273849fccd"
},
"csi": {
"driver": "rook-ceph.rbd.csi.ceph.com",
"fsType": "ext4",
"nodeStageSecretRef": {
"name": "rook-csi-rbd-node",
"namespace": "rook-ceph"
},
"volumeAttributes": {
"clusterID": "rook-ceph",
"imageFeatures": "layering",
"imageFormat": "2",
"pool": "replicapool",
"storage.kubernetes.io/csiProvisionerIdentity": "1593101040137-8081-rook-ceph.rbd.csi.ceph.com"
},
"volumeHandle": "0001-0009-rook-ceph-0000000000000001-d11d2a4d-bd2e-11ea-b56e-7a7db811cab1"
},
"persistentVolumeReclaimPolicy": "Delete",
"storageClassName": "rook-ceph-block",
"volumeMode": "Filesystem"
},
"status": {
"phase": "Bound"
}
}
GET /services/:service_code/:environment_name/persistentvolumes/:id?cluster_id=:cluster_id
Retrieve a persistent volume and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the persistent volume. |
| Attributes | |
|---|---|
id string |
The id of the persistent volume. This is the name of the resource. |
metadata object |
The metadata of the persistent volume. |
spec object |
The specification of the persistent volume. |
spec.accessModes string |
The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes). |
spec.capacity.storage string |
Storage capacity of the persistent volume. |
spec.persistentVolumeReclaimPolicy string |
One of Retain (manual reclamation), Recycle (basic scrub) or Delete (associated storage asset such as AWS EBS, GCE PD, Azure Disk, or OpenStack Cinder volume is deleted). |
spec.storageClassName string |
Storage class associated to the volume. |
spec.capacity.volumeMode string |
If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device. |
status.phase string |
Volume is in one of the following phases: Available, Bound, Released or Failed. |
Create a persistent volume
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumes"
Content-Type: application/json
{
"apiVersion": "v1",
"metadata": {
"name": "small-pvc",
"namespace": "default"
},
"spec": {
"accessModes": [
"ReadWriteOnce"
],
"resources": {
"requests": {
"storage": "10G"
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/persistentvolumes
Create a persistent volume in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the persistent volume. |
metadata object |
The metadata of the persistent volume. |
metadata.name string |
The name of the persistent volume. |
spec object |
The spec for the persistent volume. |
spec.accessModes array |
A list of access modes, the options are: ReadWriteOnce, ReadOnlyMany and ReadWriteMany. |
spec.capacity.storage string |
Measured in bytes. You can express storage as a plain integer or as a fixed-point integer using one of these suffixes: E, P, T, G, M, K. You can also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki. |
spec.<VOLUME_TYPE> object |
Volume types are identified by name and what volume types are supported differ heavily by Kubernetes deployment. The contents of the object also depend on the volume type. Examples of common volumes types are nfs, hostPath, or local. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the pod is created, if not specified will create the persistent volume in default. |
spec.storageClassName string |
Storage class associated to the volume. |
spec.claimRef array |
The name of the PersistentVolumeClaim associated to the persistent volume. |
spec.mountOptions array |
Mount options for when a Persistent Volume is mounted on a node. |
spec.nodeAffinity array |
Defines constraints that limit what nodes this volume can be accessed from. |
spec.persistentVolumeReclaimPolicy array |
One of Retain (manual reclamation), Recycle (basic scrub) or Delete (associated storage asset such as AWS EBS, GCE PD, Azure Disk, or OpenStack Cinder volume is deleted). |
spec.volumeMode array |
If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device. |
status.phase string |
Volume is in one of the following phases: Available, Bound, Released or Failed. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create persistent volume task. |
taskStatus string |
The status of the operation. |
Replace a persistent volume
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumes/my-persistent-volume?cluster_id=a_cluster_id"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "PersistentVolume",
"metadata": {
"annotations": {
"key": "value"
},
"name": "persistentvolumes-name"
},
"spec": {
"accessModes": [
"ReadWriteMany"
],
"capacity": {
"storage": "2Gi"
},
"claimRef": {
"apiVersion": "v1",
"kind": "PersistentVolumeClaim",
"name": "pv-claim-name",
"namespace": "default",
"resourceVersion": "259087",
"uid": "11957feb-1acc-4c7e-911e-f77d5d7be5ac"
},
"hostPath": {
"path": "/etc/path"
},
"persistentVolumeReclaimPolicy": "Retain",
"storageClassName": "standard",
"volumeMode": "Filesystem"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/persistentvolumes/:id?cluster_id=a_cluster_id
Replace a persistent volume in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the volume. |
metadata object |
The metadata of the volume. |
metadata.name string |
The name of the volume. |
specobject |
The specification used to replace and run the volume. |
spec.accessModesstring |
The desired access modes the volume should have. |
spec.capacity.storagestring |
The size of the claim. |
spec.hostPath.pathstring |
The path of the directory on the host. |
| Optional Attributes | |
|---|---|
metadata.annotations string |
Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. |
spec.claimRef string |
part of a bi-directional binding between PersistentVolume and PersistentVolumeClaim. Expected to be non-nil when bound. |
spec.persistentVolumeReclaimPolicy string |
What happens to a persistent volume when released from its claim. |
spec.storageClassName string |
Name of StorageClass to which this persistent volume belongs. Empty value means that this volume does not belong to any StorageClass. |
spec.volumeMode string |
Defines if a volume is intended to be used with a formatted filesystem or to remain in raw block state. Value of Filesystem is implied when not included in spec. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace volume task. |
taskStatus string |
The status of the operation. |
Delete a persistent volume
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumes/pvc-05097a93-120d-45d2?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/persistentvolumes/:id?cluster_id=:cluster_id
Delete a perstent volume from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the perstent volume. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete persistent volume task. |
taskStatus string |
The status of the operation. |
Persistent Volume Claims
List persistent volume claims
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumeclaims?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "cmc-staging-mysql/cmc-stg",
"metadata": {
"annotations": {
"pv.kubernetes.io/bind-completed": "yes",
"pv.kubernetes.io/bound-by-controller": "yes",
"volume.beta.kubernetes.io/storage-provisioner": "rook-ceph.rbd.csi.ceph.com"
},
"creationTimestamp": "2020-04-27T12:01:22.000-04:00",
"finalizers": ["kubernetes.io/pvc-protection"],
"labels": {
"app": "cmc-staging-mysql",
"chart": "mysql-0.4.5",
"heritage": "Helm",
"release": "cmc-staging"
},
"name": "cmc-staging-mysql",
"namespace": "cmc-stg",
"resourceVersion": "111495311",
"selfLink": "/api/v2/namespaces/cmc-stg/persistentvolumeclaims/cmc-staging-mysql",
"uid": "ba115a65-e3c5-4e37-8548-e37ec395e79f"
},
"spec": {
"accessModes": ["ReadWriteOnce"],
"resources": {
"requests": {
"storage": "8Gi"
}
},
"storageClassName": "rook-ceph-block",
"volumeMode": "Filesystem",
"volumeName": "pvc-ba115a65-e3c5-4e37-8548-e37ec395e79f"
},
"status": {
"accessModes": ["ReadWriteOnce"],
"capacity": {
"storage": "8Gi"
},
"phase": "Bound"
}
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/persistentvolumeclaims?cluster_id=:cluster_id
Retrieve a list of all persistent volume claims in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the persistent volume claims. |
| Attributes | |
|---|---|
id string |
The id of the persistent volume claim. This is the name and namespace of the resource. |
metadata object |
The metadata of the persistent volume claim. |
spec object |
The specification of the persistent volume claim. |
spec.accessModes string |
The requested access mode. The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes). |
spec.resources.requests.storage string |
The requested storage capacity of the persistent volume. |
spec.storageClassName string |
Storage class associated to the volume. |
spec.capacity.volumeMode string |
If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device. |
status object |
The status of the persistent volume claim. |
status.phase string |
The claim is in one of the following phases: Pending, Bound, Lost or Terminating. |
status.accessModes string |
The allocated access mode. The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes). |
status.capacity.storage string |
The allocated storage capacity. |
Get a persistent volume claim
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumeclaims/cmc-staging-mysql/cmc-stg?cluster_id=:cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "cmc-staging-mysql/cmc-stg",
"apiVersion": "v1",
"kind": "PersistentVolumeClaim",
"metadata": {
"annotations": {
"pv.kubernetes.io/bind-completed": "yes",
"pv.kubernetes.io/bound-by-controller": "yes",
"volume.beta.kubernetes.io/storage-provisioner": "rook-ceph.rbd.csi.ceph.com"
},
"creationTimestamp": "2020-04-27T12:01:22.000-04:00",
"finalizers": ["kubernetes.io/pvc-protection"],
"labels": {
"app": "cmc-staging-mysql",
"chart": "mysql-0.4.5",
"heritage": "Helm",
"release": "cmc-staging"
},
"name": "cmc-staging-mysql",
"namespace": "cmc-stg",
"resourceVersion": "111495311",
"selfLink": "/api/v2/namespaces/cmc-stg/persistentvolumeclaims/cmc-staging-mysql",
"uid": "ba115a65-e3c5-4e37-8548-e37ec395e79f"
},
"spec": {
"accessModes": ["ReadWriteOnce"],
"resources": {
"requests": {
"storage": "8Gi"
}
},
"storageClassName": "rook-ceph-block",
"volumeMode": "Filesystem",
"volumeName": "pvc-ba115a65-e3c5-4e37-8548-e37ec395e79f"
},
"status": {
"accessModes": ["ReadWriteOnce"],
"capacity": {
"storage": "8Gi"
},
"phase": "Bound"
}
}
}
GET /services/:service_code/:environment_name/persistentvolumeclaims/:id?cluster_id=:cluster_id
Retrieve a persistent volume claim and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the persistent volume claim. |
| Attributes | |
|---|---|
id string |
The id of the persistent volume claim. This is the name and namespace of the resource. |
metadata object |
The metadata of the persistent volume claim. |
spec object |
The specification of the persistent volume claim. |
spec.accessModes string |
The requested access mode. The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes). |
spec.resources.requests.storage string |
The requested storage capacity of the persistent volume. |
spec.storageClassName string |
Storage class associated to the volume. |
spec.capacity.volumeMode string |
If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device. |
status object |
The status of the persistent volume claim. |
status.phase string |
The claim is in one of the following phases: Pending, Bound, Lost or Terminating. |
status.accessModes string |
The allocated access mode. The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes). |
status.capacity.storage string |
The allocated storage capacity. |
Create a persistent volume claim
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumeclaims?cluster_id=a_cluster_id"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "PersistentVolumeClaim",
"metadata": {
"name": "small-pvc",
"namespace": "default"
},
"spec": {
"accessModes": [
"ReadWriteOnce"
],
"resources": {
"requests": {
"storage": "10G"
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/persistentvolumeclaims?cluster_id=:cluster_id
Create a persistent volume claim in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the persistent volume claims. |
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the persistent volume claim. |
metadata object |
The metadata of the persistent volume claim. |
metadata.name string |
The name of the persistent volume claim. |
spec object |
The spec for the persistent volume claim. |
spec.accessModes array |
A list of access modes, the options are: ReadWriteOnce, ReadOnlyMany and ReadWriteMany. |
spec.resources.requests.storage string |
Measured in bytes. You can express storage as a plain integer or as a fixed-point integer using one of these suffixes: E, P, T, G, M, K. You can also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the pod is created, if not specified will create the claim in default. |
spec.storageClassName string |
The storage class for the persistent volume claim, will use the default if not specified. |
spec.resources.limits object |
Limits describe the maximum number of storage resources allowed. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create persistent volume claim task. |
taskStatus string |
The status of the operation. |
Replace a persistent volume claim
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumeclaims/my-persistent-volume-claim/default?cluster_id=a_cluster_id"
Content-Type: application/json
{
"id": "pv-claim-name/default",
"apiVersion": "v1",
"kind": "PersistentVolumeClaim",
"metadata": {
"name": "pv-claim-name",
"namespace": "default"
},
"spec": {
"accessModes": [
"ReadWriteOnce"
],
"resources": {
"requests": {
"storage": "1Gi"
}
},
"storageClassName": "standard",
"volumeName": "persistentvolumes-name",
"dataSource": "dataSource"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/persistentvolumeclaims/:id?cluster_id=:cluster_id
Replace a persistent volume claim in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the claim. |
metadata object |
The metadata of the claim. |
metadata.name string |
The name of the claim. |
specobject |
The specification used to replace and run the claim. |
spec.accessModesstring |
The desired access modes the volume should have. |
spec.resources.requests.storagestring |
The size of the claim. |
spec.storageClassNamestring |
The name of the StorageClass required by the claim. |
| Optional Attributes | |
|---|---|
spec.volumeNamestring |
The binding reference to the PersistentVolume backing this claim. Only required if claim is bound. |
spec.volumemode string |
What type of volume is required by the claim. Value of Filesystem is implied when not included in claim spec. |
spec.dataSource string |
This field can be used to specify either: an existing VolumeSnapshot object, an existing PVC or an existing custom resource/object that implements data population. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace persistent volume claim task. |
taskStatus string |
The status of the operation. |
Delete a persistent volume claim
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumeclaims/cmc-staging-mysql/cmc-stg?cluster_id=:cluster_id"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/persistentvolumeclaims/:id?cluster_id=:cluster_id
Delete a perstent volume claim from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the perstent volume claim. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete persistent volume claim task. |
taskStatus string |
The status of the operation. |
Access control
Service accounts
List service accounts
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/serviceaccounts?cluster_id=:cluster_id"
The above command returns a JSON structured like this:
{
"metadata": {
"name": "vpnkit-controller",
"namespace": "kube-system",
"selfLink": "/api/v2/namespaces/kube-system/serviceaccounts/vpnkit-controller",
"uid": "b9afa8a8-3d64-4605-959f-12bb5c6cfba2",
"resourceVersion": "481",
"creationTimestamp": "2020-09-18T14:47:48Z",
"annotations": {
"kubectl.kubernetes.io/last-applied-configuration": "{\"apiVersion\":\"v1\",\"kind\":\"ServiceAccount\",\"metadata\":{\"annotations\":{},\"name\":\"vpnkit-controller\",\"namespace\":\"kube-system\"}}\n"
}
},
"secrets": [
{
"name": "vpnkit-controller-token-hl674"
}
]
}
]
}
GET /services/:service_code/:environment_name/serviceaccounts?cluster_id=:cluster_id
Retrieve a list of all service accounts in a given environment.
| Attributes | |
|---|---|
id string |
The id of the service account. |
metadata.annotations map |
The annotations of the service account. |
metadata object |
The metadata of the service account. |
metadata.creationTimestamp string |
The date of creation of the service account as a string. |
metadata.name string |
The name of the service account. |
metadata.namespace string |
The namespace in which the service account is created. |
metadata.uid object |
The UUID of the service account. |
metadata.secrets List<object> |
The secrets of the service account. |
secretsSize integer |
The number of secrets of the service account. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a service account
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/serviceaccounts/serviceaccount-name/serviceaccount-namespace?cluster_id=:cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "default",
"age": "1w5d",
"secretsSize": 1,
"metadata": {
"creationTimestamp": "2020-09-18T10:46:40.000-04:00",
"name": "default",
"namespace": "default",
"uid": "80a0de4d-a187-44c3-b691-1481220a5817"
},
"secrets": [
{
"name": "default-token-lrth9"
}
]
},
"fieldTransitions": {},
"operations": []
}
GET /services/:service_code/:environment_name/serviceaccounts/:id?cluster_id=:cluster_id
Retrieve a service account and all its info in a given environment.
| Attributes | |
|---|---|
id string |
The id of the service account. |
metadata object |
The metadata of the service account. |
metadata.creationTimestamp string |
The date of creation of the service account as a string. |
metadata.name string |
The name of the service account. |
metadata.namespace string |
The namespace in which the service account is created. |
metadata.uid object |
The UUID of the service account. |
metadata.secrets List<object> |
The secrets of the service account. |
secretsSize integer |
The number of secrets of the service account. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a service account
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/serviceaccounts?cluster_id=:cluster_id"
Content-Type: application/json
{
"apiVersion": "v1",
"metadata": {
"name": "service-account-name",
"namespace": "default"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/serviceaccounts?cluster_id=:cluster_id
Create a service account in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the service account. |
metadata object |
The metadata of the service account. |
metadata.name string |
The name of the service account. |
metadata.namespace string |
The namespace of the service account. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create service account task. |
taskStatus string |
The status of the operation. |
Replace a service account
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/serviceaccounts/service-account-name/namespace-name?cluster_id=:cluster_id"
Content-Type: application/json
{
"metadata": {
"name": "service-account-name",
"namespace": "namespace-name"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/serviceaccounts/:id?cluster_id=:cluster_id
Replace a service account in a given environment.
| Required Attributes | |
|---|---|
metadata object |
The metadata of the service account. |
metadata.name string |
The name of the service account. |
metadata.namespace string |
The namespace of the service account. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create service account task. |
taskStatus string |
The status of the operation. |
Delete a service account
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/serviceaccounts/my-service-account/my-namespace?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/serviceaccounts/:id?cluster_id=:cluster_id
Delete a service account from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to delete the service account. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete service account task. |
taskStatus string |
The status of the operation. |
Roles
List (namespace) Roles
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/roles?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "role-id",
"age": "1w4d",
"metadata": {
"creationTimestamp": "2020-09-18T10:01:26.000-04:00",
"name": "kubeadm:bootstrap-signer-clusterinfo",
"namespace": "kube-public",
"uid": "57ef0321-e44a-43c9-9f2a-e448c3a66a46"
},
"rules": [
{
"apiGroups": [],
"resourceNames": [],
"resources": [],
"verbs": []
}
]
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/roles?cluster_id=:cluster_id
Retrieve a list of all roles in a given environment.
| Attributes | |
|---|---|
id string |
The id of the role. |
metadata object |
The metadata of the role. |
metadata.creationTimestamp string |
The date of creation of the service account as a string. |
metadata.name string |
The name of the role. |
metadata.namespace string |
The namespace in which the role is created. |
metadata.uid object |
The UUID of the role. |
rules array |
The array of rules associated with this role. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a role
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/roles/role-name/role-namespace?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
The above command returns a JSON structured like this:
{
"data": {
"id": "kubeadm:bootstrap-signer-clusterinfo",
"age": "1w4d",
"apiVersion": "rbac.authorization.k8s.io/v1",
"kind": "Role",
"metadata": {
"creationTimestamp": "2020-09-18T10:01:26.000-04:00",
"name": "kubeadm:bootstrap-signer-clusterinfo",
"namespace": "kube-public",
"uid": "57ef0321-e44a-43c9-9f2a-e448c3a66a47"
},
"rules": [
{
"apiGroups": [],
"resourceNames": [],
"resources": [],
"verbs": []
}
]
}
}
GET /services/:service_code/:environment_name/roles/:id?cluster_id=:cluster_id
Retrieve a role and all its info in a given environment.
| Attributes | |
|---|---|
id string |
The id of the role. |
apiVersion string |
The API version used to retrieve this role. |
metadata object |
The metadata of the role. |
rules array |
The array of rules associated with this role. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a role
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/roles?cluster_id=:cluster_id"
Content-Type: application/json
{
"apiVersion": "rbac.authorization.k8s.io/v1",
"kind": "Role",
"namespace": "default",
"name": "test-name",
"metadata": {
"namespace": "default",
"name": "test-name"
},
"rules": [
{
"apiGroups": [
""
],
"resources": [
"resource"
],
"verbs": [
"get",
"watch"
]
}
]
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/roles?cluster_id=:cluster_id
Create a role in a given environment.
| Attributes | |
|---|---|
id string |
The id of the role. |
apiVersion string |
The API version used to create this role. |
metadata.name string |
The name of the role. |
metadata.namespace string |
The namespace of the role. |
rules array |
The array of rules associated with this role. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create role task. |
taskStatus string |
The status of the operation. |
Replace a role
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/roles/role-name/namespace-name?cluster_id=:cluster_id"
Content-Type: application/json
{
"metadata": {
"name": "role-name",
"namespace": "namespace-name"
}
"rules": [
{
"apiGroups": [
""
],
"resources": [
"resource"
],
"verbs": [
"get",
"watch",
"..."
]
}
]
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/roles/:id?cluster_id=:cluster_id
Replace a role in a given environment.
| Required Attributes | |
|---|---|
metadata object |
The metadata of the role. |
metadata.name string |
The name of the role. |
metadata.namespace string |
The namespace of the role. |
metadata.namespace string |
The namespace of the role. |
| Optional Attributes | |
|---|---|
rules array |
The array of rules associated with this role. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace role operation. |
taskStatus string |
The status of the operation. |
Delete a role
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/roles/default-token-xxxmt/default?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/roles/:id?cluster_id=:cluster_id
Delete a role from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to delete the role. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete role task. |
taskStatus string |
The status of the operation. |
Role bindings
List (namespace) role bindings
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/rolebindings?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
The above command returns a JSON structured like this:
{
"data": {
"entity": {
"id": "kubeadm:bootstrap-signer-clusterinfo",
"age": "1w5d",
"metadata": {
"creationTimestamp": "2020-09-18T10:46:32.000-04:00",
"name": "kubeadm:bootstrap-signer-clusterinfo",
"namespace": "kube-public",
"uid": "4fcfe5b9-a1c3-4b3b-9cb6-6df4a1da945f"
},
"roleRef": {
"apiGroup": "rbac.authorization.k8s.io",
"kind": "Role",
"name": "kubeadm:bootstrap-signer-clusterinfo"
},
"subjects": [
{
"apiGroup": "rbac.authorization.k8s.io",
"kind": "User",
"name": "system:anonymous"
}
]
},
"fieldTransitions": {},
"operations": []
},
}
GET /services/:service_code/:environment_name/rolebindings?cluster_id=:cluster_id
Retrieve a list of all role bindings in a given environment.
| Attributes | |
|---|---|
id string |
The id of the role binding. |
metadata object |
The metadata of the role binding. |
metadata.creationTimestamp string |
The date of creation of the role binding as a string. |
metadata.name string |
The name of the role binding. |
metadata.namespace string |
The namespace in which the role binding is created. |
metadata.uid object |
The UUID of the role binding. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a role binding
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/rolebindings/rolebinding-name/rolebinding-namespace?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
The above command returns a JSON structured like this:
{
"data": {
"id": "kubeadm:bootstrap-signer-clusterinfo",
"age": "1w5d",
"metadata": {
"creationTimestamp": "2020-09-18T10:46:32.000-04:00",
"name": "kubeadm:bootstrap-signer-clusterinfo",
"namespace": "kube-public",
"uid": "4fcfe5b9-a1c3-4b3b-9cb6-6df4a1da945f"
},
"roleRef": {
"apiGroup": "rbac.authorization.k8s.io",
"kind": "Role",
"name": "kubeadm:bootstrap-signer-clusterinfo"
},
"subjects": [
{
"apiGroup": "rbac.authorization.k8s.io",
"kind": "User",
"name": "system:anonymous"
}
]
},
"fieldTransitions": {},
"operations": []
},
}
GET /services/:service_code/:environment_name/rolebindings/:id?cluster_id=:cluster_id
Retrieve a role binding and all its info in a given environment.
| Attributes | |
|---|---|
id string |
The id of the role binding. |
apiVersion string |
The API version used to retrieve this role binding. |
metadata object |
The metadata of the role binding. |
roleRefobject |
The role to bind. Can reference a Role in the current namespace or a ClusterRole in the global namespace. |
subjects array |
The array of subjects associated with this role binding. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a role binding
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/rolebindings?cluster_id=:cluster_id"
Content-Type: application/json
{
"kind": "Rolebinding",
"metadata": {
"name": "rolebinding-name",
"namespace": "namespace-name"
},
"roleRef": {
"apiGroup": "rbac.authorization.k8s.io",
"kind": "Role",
"name": "role-name"
},
"subjects": [
{
"kind": "ServiceAccount",
"name": "service-account-name",
"namespace": "service-account-namespace"
},
{
"kind": "Group",
"name": "group-name",
"namespace": "group-namespace"
},
{
"kind": "User",
"name": "user-name",
}
]
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/rolebindings?cluster_id=:cluster_id
Create a role binding in a given environment.
| Required Attributes | |
|---|---|
metadata object |
The metadata of the role binding. |
metadata.name string |
The name of the role binding. |
metadata.namespace string |
The namespace of the role binding. |
roleRefobject |
The role to bind. Can reference a Role in the current namespace or a ClusterRole in the global namespace. |
subjectsarray |
Subjects hold references to the objets the role applies to. Can be users, groups, or service accounts. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create role binding task. |
taskStatus string |
The status of the operation. |
Replace a role binding
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/rolebindings/rolebinding-name/namespace-name?cluster_id=:cluster_id"
Content-Type: application/json
{
"metadata": {
"name": "service-account-name",
"namespace": "namespace-name"
},
"roleRef": {
"apiGroup": "",
"kind": "Role",
"name": "role-name"
},
"subjects": [
{
"kind": "ServiceAccount",
"name": "default",
"namespace": "default"
},
{
"kind": "user",
"name": "user1",
}
]
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/rolebindings/:id?cluster_id=:cluster_id
Replace a role binding in a given environment.
| Required Attributes | |
|---|---|
metadata object |
The metadata of the role binding. |
metadata.name string |
The name of the role binding. |
metadata.namespace string |
The namespace of the role binding. |
roleRefobject |
The role to bind. Can reference a Role in the current namespace or a ClusterRole in the global namespace. |
subjectsarray |
Subjects hold references to the objets the role applies to. Can be users, groups, or service accounts. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace role binding operation. |
taskStatus string |
The status of the operation. |
Delete a role binding
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/rolebindings/default-token-xxxmt/default?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
json { "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b", "taskStatus": "PENDING" }DELETE /services/:service_code/:environment_name/rolebindings/:id?cluster_id=:cluster_id
Delete a role binding from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to delete the role binding. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete role binding task. |
taskStatus string |
The status of the operation. |
Swift plugin
The Swift plugin provides endpoints for carrying out operations on Swift containers and objects. It also enforces CloudMC's environment-centric multi-tenancy model and RBAC over top of Swift.
Containers or Buckets
Create and manage your containers/buckets.
List containers/buckets
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/swift/example/buckets"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "private",
"name": "private",
"isPublic": false,
"displaySize": {
"value": "0",
"unitKey": "units.filesizes.B"
},
"size": 0,
"objectCount": 0,
"accessType": "private",
"locked": false,
"storagePolicy": "Quebec"
},
{
"id": "public",
"name": "public",
"isPublic": true,
"displaySize": {
"value": "81",
"unitKey": "units.filesizes.B"
},
"size": 81,
"objectCount": 6,
"accessType": "public",
"locked": false,
"storagePolicy": "Quebec"
}
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/buckets
Retrieve a list of all containers in a given environment.
| Attributes | |
|---|---|
id string |
The id of the container. |
name string |
The name of the container. |
isPublicboolean |
Specifies if the container is public or not. |
displaySizeObject |
Object containing the information to display the size in the UI. |
sizestring |
The size in bytes of the container. |
objectCountstring |
The number of object which are part of the container. |
accessTypestring |
The access type of the container. It can either be public or private. |
lockedstring |
Identify if the container is locked or not. |
storePolicystring |
The store policy applying to the container. |
Retrieve a container
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/swift/example/buckets/private"
The above command returns a JSON structured like this:
{
"id": "private",
"name": "private",
"isPublic": false,
"displaySize": {
"value": "0",
"unitKey": "units.filesizes.B"
},
"size": 0,
"objectCount": 0,
"accessType": "private",
"locked": false,
"storagePolicy": "Quebec"
}
GET /services/:service_code/:environment_name/buckets/:id
Retrieve a container in a given environment.
| Attributes | |
|---|---|
id string |
The id of the container. |
name string |
The name of the container. |
isPublicboolean |
Specifies if the container is public or not. |
displaySizeObject |
Object containing the information to display the size in the UI. |
sizestring |
The size in bytes of the container. |
objectCountstring |
The number of object which are part of the container. |
accessTypestring |
The access type of the container. It can either be public or private. |
lockedboolean |
Identify if the container is locked or not. |
storePolicystring |
The store policy applying to the container. |
Create a container
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/swift/example/buckets"
Request body example:
{
"name": "newBucket",
"isPublic": true
}
POST /services/:service_code/:environment_name/buckets
Create a new container.
| Required | |
|---|---|
name string |
The name of the container. It cannot exceed 256 characters and cannot contain '/'. |
| Optional | |
|---|---|
isPublicboolean |
Specifies if the container is public or private. The default value is false. |
Delete a container
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/swift/example/buckets/containerToDelete"
DELETE /services/:service_code/:environment_name/buckets/:id
Delete an existing container.
Rename a container
Rename the container to a new name.
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/swift/example/buckets/containerToRename?operation=rename"
Request body example:
{
"name": "newContainerName"
}
POST /services/:service_code/:environment_name/buckets/:id?operation=rename
| Required | |
|---|---|
namestring |
The new name of the container. |
Objects
Create and manage your objects.
Preview objects
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/swift/my-env/objects/my-private-bucket/my-object.jpg/redirect?operation=preview"
GET /services/:service_code/:environment_name/objects/:id/redirect
Preview both public and private objects. Previews of private objects will generate a temporary URL that provides GET access for limited time. The generated URL will expire after one hour.
StackPath plugin
The StackPath plugin provides endpoints for carrying out operations on CloudMC Edge computing entities. It also enforces CloudMC's environment-centric multi-tenancy model and RBAC on top of StackPath.
Edge compute
Workloads
StackPath Edge Computing uses the concept of workloads to organize different applications. A workload can consist of one container or virtual machine image that is deployed to one or many locations.
Deploy and manage your workloads.
List workloads
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/workloads"
The above command returns a JSON structured like this:
{
"data": [
{
"name": "container-workload",
"stackId": "a397735b-66d2-49ba-b665-e77acb944481",
"slug": "container-workload",
"version": "1",
"created": "2021-02-22T17:32:27.202428099Z",
"type": "CONTAINER",
"network": "default",
"cpu": "1",
"memory": "2Gi",
"isRemoteManagementEnabled": false,
"image": "nginx",
"addImagePullCredentialsOption": false,
"environmentVariables": [
{
"key": "USER",
"value": "my-user"
}
],
"secretEnvironmentVariables": [
{
"key": "PASSWORD",
"value": "[REDACTED]"
}
],
"addAnyCastIpAddress": false,
"anycastIpAddress": "185.85.196.7",
"commands": [
"/bin/sh -c \"sleep 50\""
],
"specs": "SP-1",
"persistentStorages" : [
{
"path": "/lib/data/newFolder",
"size": 1,
}
],
"deployments": [
{
"name": "deployment-lax",
"pops": [
"LAX"
],
"enableAutoScaling": true,
"cpuUtilization": 50,
"minInstancesPerPop": "1",
"maxInstancesPerPop": "2"
}, {
"name": "deployment-mia",
"pops": [
"MIA"
],
"enableAutoScaling": false,
"instancesPerPop": "1",
"cpuUtilization": 0,
}
],
"id": "af951a00-5d1f-4c0a-85a4-b0714e833cd1",
"status": "ACTIVE"
}, {
"id": "419be644-b2e7-4574-aad9-52e1cc0e6199",
"name": "vm-workload",
"stackId": "4f246958-595d-4ead-ae56-a88cff334b97",
"slug": "vm-workload",
"version": "10",
"created": "2020-11-27T20:11:09.563675315Z",
"type": "VM",
"network": "default",
"specs": "SP-1",
"cpu": "1",
"memory": "2Gi",
"isRemoteManagementEnabled": false,
"image": "stackpath-edge/centos-7:v202007311835",
"addAnyCastIpAddress": false,
"anycastIpAddress": "None",
"firstBootSshKey": "ssh-rsa...",
"persistentStorages" : [
{
"path": "/lib/data/newFolder",
"size": 1,
}
],
"deploymentName": "deployment-name",
"deploymentPops": [
"YYZ"
],
"enableAutoScaling": false,
"deploymentInstancePerPops": 3,
"status": "ACTIVE"
}
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/workloads
Retrieve a list of all workloads in a given environment.
| Attributes | |
|---|---|
addImagePullCredentialsOptionboolean |
It is used to indicate if additional credentials to pull container image are provided or not. Only applicable to workloads of type 'CONTAINER'. |
anycastIpAddressstring |
The Anycast IP address assigned to a workload. If there is no IP assigned to the workload then the value of this attribute will be None. |
commandsArray[string] |
The commands that start a container. Only applicable to workloads of type 'CONTAINER'. |
containerEmail string |
The email address to use for the docker registry account. Only applicable to workloads of type 'CONTAINER' and addImagePullCredentialsOption is 'true'. |
containerServer string |
The server that the credentials should be used with. This value will default to the docker hub registry when not set. Only applicable to workloads of type 'CONTAINER' and addImagePullCredentialsOption is 'true'. |
containerUsername string |
The username used to authenticate the image pull. Only applicable to workloads of type 'CONTAINER' and addImagePullCredentialsOption is 'true'. |
cpustring |
The number of vCPUs for the workload's instance. |
createdstring |
Creation timestamp of the workload. |
deployments.cpuUtilization int |
The percentage of CPU utilization. Only applicable if autoscaling is enabled. |
deployments.enableAutoScaling boolean |
Specifies if autoscaling is enabled. If enabled, then cpuUtilization , minInstancesPerPop and maxInstancesPerPop are shown. |
deployments.instancesPerPopint |
The number of instances per point of presence. Only applicable if autoscaling is not enabled. |
deployments.maxInstancesPerPop int |
The maximum number of instances per PoP. Only applicable if autoscaling is enabled. Should be greater than zero and less than 50. |
deployments.minInstancesPerPop int |
The minimum number of instances per PoP. Only applicable if autoscaling is enabled. Should be greater than zero and less than 50. |
deployments.namestring |
The name of the deployment. |
deployments.popsArray[string] |
The points of presence of a deployment. In the regex format [A-Z]{3, 3}. |
deploymentsArray[Object] |
The list of deployment targets. |
environmentVariables.key string |
The location to obtain a value for an environment variable. When editing a workload, include keys you wish to preserve. Keys not included in the body will be removed. |
environmentVariables.value string |
An environment variable's value. |
environmentVariables Array[Object] |
A list of environment variables. Only applicable to workloads of type 'CONTAINER'. |
firstBootSshKeystring |
The ssh key(s) for the VM image. Keys are delimited by a newline, \n. Only applicable to workloads of type 'VM'. |
idstring |
A workload's unique identifier. |
imagestring |
The workload's instance operating system image. |
isRemoteManagementEnabledboolean |
Specifies if remote management is enabled on workload instance or not. |
memorystring |
The memory size for the workload's instance. |
namestring |
The display name of the workload. |
networkstring |
Network interfaces to bind to the workload's instances. |
persistentStoragesArray[Object] |
Persistent storage volumes used by the workload. |
persistentStorages.pathstring |
The path in an instance to mount a volume. |
persistentStorages.sizeint |
The size of the mounted volume (in GB). |
secretEnvironmentVariables.key string |
The location to obtain a value for a secret environment variable. When editing a workload, include keys you wish to preserve. Keys not included in the body will be removed. |
secretEnvironmentVariables.value string |
A secret environment variable's value. When editing a workload, setting an existing environment variable's value to [REDACTED] will preserve the existing secret. |
secretEnvironmentVariables Array[Object] |
A list of sensitive environment variables. Only applicable to workloads of type 'CONTAINER'. |
slugstring |
A workload's programmatic name. Workload slugs are used to build its instances names. |
specsstring |
Specification type for resources which are allocated to each instance in a workload. |
stackIdstring |
The ID of the stack that a workload belongs to. |
statusstring |
The status of the workload. It can be either ACTIVE or DISABLED. |
typestring |
Specify whether a workload is a VM-based workload or container-based. |
userDatastring |
User data compatible with cloud-init to be run on the workload's instances. |
versionstring |
A version number for the workload. Versions start at 1 when they are created and increment by 1 every time they are updated. |
Retrieve a workload
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/workloads/1b932678-1038-4ab4-9fa4-c4c06e696e20"
The above command returns a JSON structured like this:
{
"data": {
"name": "container-workload",
"stackId": "a397735b-66d2-49ba-b665-e77acb944481",
"slug": "container-workload",
"version": "1",
"created": "2021-02-22T17:32:27.202428099Z",
"type": "CONTAINER",
"network": "default",
"cpu": "1",
"memory": "2Gi",
"userData":"package-upgrade: true",
"isRemoteManagementEnabled": false,
"image": "nginx",
"addImagePullCredentialsOption": false,
"environmentVariables": [
{
"key": "USER",
"value": "my-user"
}
],
"secretEnvironmentVariables": [
{
"key": "PASSWORD",
"value": "[REDACTED]"
}
],
"addAnyCastIpAddress": false,
"anycastIpAddress": "None",
"commands": [
"/bin/sh -c \"sleep 50\""
],
"specs": "SP-1",
"persistentStorages" : [
{
"path": "/lib/data/newFolder",
"size": 1,
}
],
"deployments": [
{
"name": "deployment-lax",
"pops": [
"LAX"
],
"enableAutoScaling": true,
"cpuUtilization": 50,
"minInstancesPerPop": "1",
"maxInstancesPerPop": "2"
}, {
"name": "deployment-mia",
"pops": [
"MIA"
],
"enableAutoScaling": false,
"instancesPerPop": "1",
"cpuUtilization": 0,
}
],
"id": "af951a00-5d1f-4c0a-85a4-b0714e833cd1",
"status": "ACTIVE"
}
}
GET /services/:service_code/:environment_name/workloads/:id
Retrieve a workload in a given environment.
| Attributes | |
|---|---|
addImagePullCredentialsOptionboolean |
It is used to indicate if additional credentials to pull container image are provided or not. Only applicable to workloads of type 'CONTAINER'. |
anycastIpAddressstring |
The Anycast IP address assigned to a workload. If there is no IP assigned to the workload then the value of this attribute will be None. |
commandsArray[string] |
The commands that start a container. Only applicable to workloads of type 'CONTAINER'. |
containerEmail string |
The email address to use for the docker registry account. Only applicable to workloads of type 'CONTAINER' and addImagePullCredentialsOption is 'true'. |
containerServer string |
The server that the credentials should be used with. This value will default to the docker hub registry when not set. Only applicable to workloads of type 'CONTAINER' and addImagePullCredentialsOption is 'true'. |
containerUsername string |
The username used to authenticate the image pull. Only applicable to workloads of type 'CONTAINER' and addImagePullCredentialsOption is 'true'. |
cpustring |
The number of vCPUs for the workload's instance. |
createdstring |
Creation timestamp of the workload. |
deployments.cpuUtilization int |
The percentage of CPU utilization. Only applicable if autoscaling is enabled. |
deployments.enableAutoScaling boolean |
Specifies if autoscaling is enabled. If enabled, then cpuUtilization , minInstancesPerPop and maxInstancesPerPop are shown. |
deployments.instancesPerPopint |
The number of instances per point of presence. Only applicable if autoscaling is not enabled. |
deployments.maxInstancesPerPop int |
The maximum number of instances per PoP. Only applicable if autoscaling is enabled. Should be greater than zero and less than 50. |
deployments.minInstancesPerPop int |
The minimum number of instances per PoP. Only applicable if autoscaling is enabled. Should be greater than zero and less than 50. |
deployments.namestring |
The name of the deployment. |
deployments.popsArray[string] |
The points of presence of a deployment. In the regex format [A-Z]{3, 3}. |
deploymentsArray[Object] |
The list of deployment targets. |
environmentVariables.key string |
The location to obtain a value for an environment variable. When editing a workload, include keys you wish to preserve. Keys not included in the body will be removed. |
environmentVariables.value string |
An environment variable's value. |
environmentVariables Array[Object] |
A list of environment variables. Only applicable to workloads of type 'CONTAINER'. |
firstBootSshKeystring |
The ssh key(s) for the VM image. Keys are delimited by a newline, \n. Only applicable to workloads of type 'VM'. |
idstring |
A workload's unique identifier. |
imagestring |
The workload's instance operating system image. |
isRemoteManagementEnabledboolean |
Specifies if remote management is enabled on workload instance or not. |
memorystring |
The memory size for the workload's instance. |
namestring |
The display name of the workload. |
networkstring |
Network interfaces to bind to the workload's instances. |
persistentStoragesArray[Object] |
Persistent storage volumes used by the workload. |
persistentStorages.pathstring |
The path in an instance to mount a volume. |
persistentStorages.sizeint |
The size of the mounted volume (in GB). |
secretEnvironmentVariables.key string |
The location to obtain a value for a secret environment variable. When editing a workload, include keys you wish to preserve. Keys not included in the body will be removed. |
secretEnvironmentVariables.value string |
A secret environment variable's value. When editing a workload, setting an existing environment variable's value to [REDACTED] will preserve the existing secret. |
secretEnvironmentVariables Array[Object] |
A list of sensitive environment variables. Only applicable to workloads of type 'CONTAINER'. |
slugstring |
A workload's programmatic name. Workload slugs are used to build its instances names. |
specsstring |
Specification type for resources which are allocated to each instance in a workload. |
stackIdstring |
The ID of the stack that a workload belongs to. |
statusstring |
The status of the workload. It can be either ACTIVE or DISABLED. |
typestring |
Specify whether a workload is a VM-based workload or container-based. |
userDatastring |
User data compatible with cloud-init to be run on the workload's instances. |
versionstring |
A version number for the workload. Versions start at 1 when they are created and increment by 1 every time they are updated. |
Create a workload
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/workloads"
Request body example for a VM Workload type:
{
"name":"vm-workload",
"slug":"vm-workload",
"type":"VM",
"image":"stackpath-edge/centos-7-cpanel:v201905241955",
"addAnyCastIpAddress":false,
"ports": [
{
"publicPort": "80",
"protocol": "TCP",
"publicPortDesc": "rule-name"
}
],
"firstBootSshKey":"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDcYr9OnzsDfYVW2I1kX/iYJ0mPG490bI5mbxbOAKPLMuWLguxRohX804j1XbwZJ+Sna+9rSfxaYA8vgd1MoYX10l9cnMLx/MMbYp4ZquauN4pGY3WoDeCqsTss3VUMW+7RFBILpU3SJTlDV02FI36D3IXb4A8XymCyU3KC99XXTfTQsuKC+WFRMsTWtklrasqCVd5yEG90i/aJc6A3TZGOYgPFNEeVYvNDaJmIkb3y4FfShoBIMgZRt0ay7SvWZUvyfvyNmK5W9ePdhZZ58R+7tQNmCzjQ4v0suWRuGJ/XL3+03w3HEsDdQx+noL+R+qAjoNFwc0spBBhJK+Q4ADqr nothing@gmail.com \nssh-rsa...",
"userData":"package-upgrade: true",
"specs":"SP-1",
"persistentStorages" : [
{
"path": "/lib/data/newFolder",
"size": 1,
}
],
"deployments": [
{
"name": "deployment-name",
"enableAutoScaling": false,
"pops": ["MIA"],
"instancesPerPop": "1"
}
]
}
Request body example for a CONTAINER Workload type:
{
"type": "CONTAINER",
"name": "container-workload",
"slug": "container-workload",
"image": "nginx",
"addAnyCastIpAddress": false,
"ports": [
{
"publicPort": "80",
"protocol": "TCP",
"publicPortDesc": "rule-name"
}
],
"specs": "SP-1",
"persistentStorages" : [
{
"path": "/lib/data/newFolder",
"size": 1,
}
],
"userData":"package-upgrade: true",
"commands": [
"/bin/sh -c \"sleep 50\""
],
"environmentVariables": [
{
"key": "USER",
"value": "my-user"
}
],
"secretEnvironmentVariables": [
{
"key": "PASSWORD",
"value": "my-password"
}
],
"deployments": [
{
"name": "deployment-mia",
"enableAutoScaling": false,
"pops": [
"MIA"
],
"instancesPerPop": "1"
},
{
"name": "deployment-lax",
"pops": [
"LAX"
],
"enableAutoScaling": true,
"minInstancesPerPop": 1,
"maxInstancesPerPop": 2,
"cpuUtilization": 50
}
]
}
The above commands return a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/workloads
Create a new workload in a given environment.
| Required | |
|---|---|
deployments.enableAutoScaling boolean |
Specifies if autoscaling is enabled. If enabled, then cpuUtilization , minInstancesPerPop and maxInstancesPerPop are required. |
deployments.namestring |
The name of the deployment. |
deployments.popsArray[string] |
The points of presence of a deployment. In the regex format [A-Z]{3, 3}. |
deploymentsArray[Object] |
The list of deployment targets. |
firstBootSshKeystring |
If creating a VM-based workload, SSH keys are required. Multiple SSH keys can be separated by newlines \n. |
imagestring |
Either the location of a Docker image to run as a container or the image to use for the virtual machine. If for a virtual machine, this is in the format of /[:]. If the image tag portion is omitted, 'default' is assumed which is the most recently created, ready, and non-deprecated image of that slug. A set of common images is present on the 'stackpath-edge' stack. |
namestring |
The name of the workload. The workload name must not exceed 18 characters. |
specsstring |
Specification type for resources which are allocated to each instance in a workload. Supported specifications are SP-1 (1 vCPU, 2 GB RAM),SP-2 (2 vCPU, 4 GB RAM),SP-3 (2 vCPU, 8GB RAM),SP-4 (4 vCPU, 16 GB RAM),SP-5 (8 vCPU, 32 GB RAM). |
typestring |
Specify whether a workload is a VM-based workload or container-based. Can be either VM or CONTAINER. |
| Optional | |
|---|---|
addAnyCastIpAddressboolean |
Option to AnyCast IP Address. |
addImagePullCredentialsOption boolean |
It is used to indicate if additional credentials to pull container image are provided or not. |
commandsArray[string] |
The commands that start a container. Only applicable to workloads of type 'CONTAINER'. Commands cannot be updated or removed after workload creation. |
containerEmail string |
The email address to use for the docker registry account |
containerPassword string |
The password used to authenticate the image pull. |
containerServer string |
The server that the credentials should be used with. This value will default to the docker hub registry when not set. |
containerUsername string |
The username used to authenticate the image pull. |
deployments.cpuUtilization int |
The percentage of CPU utilization. Only applicable if autoscaling is enabled. |
deployments.instancesPerPopint |
The number of instances per point of presence. Only applicable if autoscaling is not enabled. |
deployments.maxInstancesPerPop int |
The maximum number of instances per PoP. Only applicable if autoscaling is enabled. Should be greater than zero and less than 50. |
deployments.minInstancesPerPop int |
The minimum number of instances per PoP. Only applicable if autoscaling is enabled. Should be greater than zero and less than 50. |
environmentVariables.key string |
The location to obtain a value for an environment variable. When editing a workload, include keys you wish to preserve. Keys not included in the body will be removed. |
environmentVariables.value string |
An environment variable's value. |
environmentVariables Array[Object] |
A list of environment variables. Only applicable to workloads of type 'CONTAINER'. |
persistentStoragesArray[Object] |
Persistent storage volumes used by the workload. |
persistentStorages.pathstring |
The path in an instance to mount a volume. |
persistentStorages.sizeint |
The size of the mounted volume (in GB). |
ports.protocolstring |
Protocol for the network policy rule. Supported protocols are: TCP, UDP and TCP_UDP. |
ports.publicPortstring |
A single port, such as 80 or a port range, such as 1024-65535 for which a network policy rule will be created for the workload. |
ports.publicPortDescstring |
A summary of what the network policy rule does or a name for it. It is highly recommended to give a unique description to easily identify a network policy rule. Defaults to an empty string if not provided. |
ports.publicPortSrcstring |
A subnet that will define all the IPs allowed by the network policy rule. Defaults to 0.0.0.0/0 if not specified. |
ports Array[Object] |
A list of network interfaces that will be created for each workload instance. |
secretEnvironmentVariables.key string |
The location to obtain a value for a secret environment variable. When editing a workload, include keys you wish to preserve. Keys not included in the body will be removed. |
secretEnvironmentVariables.value string |
A secret environment variable's value. When editing a workload, setting an existing environment variable's value to [REDACTED] will preserve the existing secret. |
secretEnvironmentVariables Array[Object] |
A list of sensitive environment variables. Only applicable to workloads of type 'CONTAINER'. |
slugstring |
A workload's programmatic name. Workload slugs are used to build its instances names. If not provided, defaults to workload's name. It must not exceed 18 characters. |
userDatastring |
User data compatible with cloud-init to be run on the workload's instances. This should only be set for a VM-based workload. |
Edit a workload
curl -X PUT \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/workloads/1b932678-1038-4ab4-9fa4-c4c06e696e20"
Request body example for a VM Workload type:
{
"name": "my-vm-workload",
"type": "VM",
"specs": "SP-1",
"userData":"package-upgrade: true",
"deployments": [
{
"name": "toronto-1",
"pops": [
"YYZ"
],
"enableAutoScaling": true,
"minInstancesPerPop": 1,
"maxInstancesPerPop": 2,
"cpuUtilization": 50
}
]
}
Request body example for a CONTAINER Workload type:
{
"name": "my-container-workload",
"type": "CONTAINER",
"image": "redis:alpine",
"secretEnvironmentVariables": [
{
"key": "PASSWORD",
"value": "my-password"
},
{
// set value to [REDACTED] to preserve existing secret
"key": "PRIVATE-KEY",
"value": "[REDACTED]"
}
],
"addImagePullCredentialsOption": true,
"containerUsername": "username",
"containerServer": "container.server.io",
"containerEmail": "myemail@email.com",
"containerPassword": "my-password",
"specs": "SP-2",
"deployments": [
{
"name": "toronto-1",
"enableAutoScaling": false,
"pops": [
"YYZ"
],
"instancesPerPop": "1"
}
]
}
The above commands return a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/workloads/:id
Edit a workload in a given environment.
| Required | |
|---|---|
deployments.enableAutoScaling boolean |
Specifies if autoscaling is enabled. If enabled, then cpuUtilization , minInstancesPerPop and maxInstancesPerPop are required. |
deployments.namestring |
The name of the deployment. |
deployments.popsArray[string] |
The points of presence of a deployment. In the regex format [A-Z]{3, 3}. |
deploymentsArray[Object] |
The list of deployment targets. |
imagestring |
The location of a Docker image to run as a container. Only editable when type is equal to CONTAINER. |
namestring |
The name of the workload. The workload name must not exceed 18 characters. |
specsstring |
Specification type for resources which are allocated to each instance in a workload. |
typestring |
Specify whether a workload is a VM-based workload or container-based. Can be either VM or CONTAINER. |
| Optional | |
|---|---|
addImagePullCredentialsOptionboolean |
It is used to indicate if additional credentials to pull container image are provided or not. Only available when type is equal to CONTAINER. |
containerEmailstring |
The password that should be used to authenticate the image pull. Only available when type is equal to CONTAINER. |
containerPasswordstring |
The password that should be used to authenticate the image pull. Only available when type is equal to CONTAINER. |
containerServerstring |
The server that the credentials should be used with. This value will default to the docker hub registry when not set. Only available when type is equal to CONTAINER. |
containerUsernamestring |
The username that should be used for authenticate the image pull. Only available when type is equal to CONTAINER. |
deployments.cpuUtilizationinteger |
The average CPU utlilization threshold to be reached before deploying a new instance. Only required if autoscaling is enabled. |
deployments.instancesPerPopinteger |
The number of deployments per point of presence. Only required if autoscaling is not enabled. |
deployments.maxInstancesPerPopinteger |
The maximum number of instances per point of presence. Only required if autoscaling is enabled. |
deployments.minInstancesPerPopinteger |
The minimum number of instances per point of presence. Only required if autoscaling is enabled. |
environmentVariables.key string |
The location to obtain a value for an environment variable. When editing a workload, include keys you wish to preserve. Keys not included in the body will be removed. |
environmentVariables.value string |
An environment variable's value. |
environmentVariables Array[Object] |
A list of environment variables. Only applicable to workloads of type 'CONTAINER'. |
secretEnvironmentVariables.key string |
The location to obtain a value for a secret environment variable. When editing a workload, include keys you wish to preserve. Keys not included in the body will be removed. |
secretEnvironmentVariables.value string |
A secret environment variable's value. When editing a workload, setting an existing environment variable's value to [REDACTED] will preserve the existing secret. |
secretEnvironmentVariables Array[Object] |
A list of sensitive environment variables. Only applicable to workloads of type 'CONTAINER'. |
userDatastring |
User data compatible with cloud-init to be run on the workload's instances. This should only be set for a VM-based workload. |
Delete a workload
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/workloads/1b932678-1038-4ab4-9fa4-c4c06e696e20"
The above command returns a JSON structured like this:
{
"taskId": "ef70cafa-0544-4709-a66a-c68595ee105a",
"taskStatus": "SUCCESS"
}
DELETE /services/:service_code/:environment_name/workloads/:id
Delete a workload in a given environment.
| Attributes | |
|---|---|
taskId string |
The task id related to the workload deletion. |
taskStatus string |
The status of the operation. |
Edit workload settings
Change a workload specific settings in a given environment. At the moment, only isRemoteManagementEnabled is supported for this operation. Any other attributes will be ignored.
curl -X PATCH \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/workloads/1b932678-1038-4ab4-9fa4-c4c06e696e20"
Request body example:
{
"isRemoteManagementEnabled": false
}
The above commands return a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
PATCH /services/:service_code/:environment_name/workloads/:id
Instances
Manage your workload instances.
List instances
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/instances?workloadId=e485fe8c-e1de-40f7-b3b3-a43700441e0e"
The above command returns a JSON structured like this:
{
"data": [
{
"stackId": "asd04459-1ccf-4a0d-8aaa-98d0f52dd2f3",
"workloadId": "e485fe8c-e1de-40f7-b3b3-a43700441e0e",
"name": "test-dep1-lax-0",
"ipAddress": "10.128.16.2",
"publicIpAddress": "151.139.71.25",
"location": "Los Angeles",
"createdDate": "2020-11-10T16:52:15Z",
"startedDate": "2020-11-10T16:52:15Z",
"id": "e485fe8c-e1de-40f7-b3b3-a43700441e0e/instance-name-1",
"status": "RUNNING"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/instance?workloadId=:workloadId
Retrieve a list of all workload instance in a given environment for a given workload ID.
| Query Params | |
|---|---|
workloadIdstring |
The workload ID to get the instances for. It is mandatory. |
| Attributes | |
|---|---|
idstring |
The instance ID. It is the combination of |
namestring |
The instance name. |
statusstring |
The instance status. Possible values are: RUNNING, STARTING, SCHEDULING. |
stackIdUUID |
The stack ID to which this instance belongs. |
workloadIdUUID |
The workload ID to which this instance belongs. |
ipAddressstring |
The internal IP address associated with the instance. |
publicIpAddressstring |
The public IP address associated with the instance. |
locationstring |
The instance location. |
createdDatestring |
The instance creation date. |
startedDatestring |
The instance started date. |
Retrieve an instance
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/instances/e485fe8c-e1de-40f7-b3b3-a43700441e0e/instance-name-1"
The above command returns a JSON structured like this:
{
"data": {
"stackId": "asd04459-1ccf-4a0d-8aaa-98d0f52dd2f3",
"workloadId": "e485fe8c-e1de-40f7-b3b3-a43700441e0e",
"name": "instance-name-1",
"ipAddress": "10.128.16.2",
"publicIpAddress": "151.139.71.25",
"location": "Los Angeles",
"createdDate": "2020-11-10T16:52:15Z",
"startedDate": "2020-11-10T16:52:15Z",
"id": "e485fe8c-e1de-40f7-b3b3-a43700441e0e/instance-name-1",
"status": "RUNNING"
}
}
GET /services/:service_code/:environment_name/instances/:id
Retrieve an instance in a given environment with the specific ID.
| Attributes | |
|---|---|
idstring |
The instance ID. It is the combination of |
namestring |
The instance name. |
statusstring |
The instance status. Possible values are: RUNNING, STARTING, SCHEDULING. |
stackIdUUID |
The stack ID to which this instance belongs. |
workloadIdUUID |
The workload ID to which this instance belongs. |
ipAddressstring |
The internal IP address associated with the instance. |
publicIpAddressstring |
The public IP address associated with the instance. |
locationstring |
The instance location. |
createdDatestring |
The instance creation date. |
startedDatestring |
The instance started date. |
Restart an instance
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/instances/workload-id1/instance-name-1?operation=restart"
POST /services/:service_code/:environment_name/instances/:id?operation=restart
Restart an instance in a given environment with the specific ID.
Access the console of an instance
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/instances/workload-id1/instance-name-1?operation=accessconsole"
Request body example(s):
{
"vmRemoteAccessType": "VNC"
}
The above command(s) return(s) JSON structured like this:
{
"taskId": "c50390c7-9d5b-4af4-a2da-e2a2678a83e8",
"taskStatus": "PENDING"
}
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/tasks/c50390c7-9d5b-4af4-a2da-e2a2678a83e8"
The above command(s) return(s) JSON structured like this:
{
"data": {
"id": "f44382a4-82e6-45f6-9153-6aa5ec69eafd",
"status": "SUCCESS",
"created": "2021-04-20T20:58:59.952881-04:00",
"result": {
"clientId": "1e15e2050fe44771c5dd82dcf07c",
"clientSecret": "c3507b64a1cfe8a973d7aa234d7581dd99c732e2c1184f9ac90f803b83ad1887",
"sshCommand": "ssh -p 9600 -t test-stack-8x5ppioikq-env.w-jdias-cmp-wi-jdias-edh-ord-0.container-0.0cbc2e63dffa4fa6b183fafeeb575c95@container-console.edgeengine.io /bin/bash"
}
}
}
POST /services/:service_code/:environment_name/instances/:id?operation=accessconsole
Access the console of an instance in a given environment with the specific ID.
For container type instances, the containerRemoteAccessCommand is required. For VM type instances, the vmRemoteAccessType is required.
| Optional | Description | Default |
|---|---|---|
containerRemoteAccessCommandstring |
The command to execute on the container instance. ex. /bin/bash | /bin/bash |
vmRemoteAccessTypeVmRemoteAccessType |
The remote access type. Can be either SERIAL or VNC. Invalid value will be ignored and the default will be used. | SERIAL |
| Attributes | |
|---|---|
idstring |
The task's ID. |
statusstring |
The task's status. |
createdDate |
The task's creation date. |
resultObject |
The task result, containing details required to access the instance's console. |
result.sshCommandString |
The command to execute to access the instance's console. |
result.clientSecretString |
The secret used to login, for which you will be prompted after executing the sshCommand. |
result.clientIdUUID |
The id of the client used to login. |
Network policy rules
Network policy rules allows you to control inbound and outbound traffic to your workload.
List network policy rules
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/networkpolicyrules"
The above command returns a JSON structured like this:
{
"data": [
{
"stackId": "bcc60174-50e6-44e4-bd45-463845124d87",
"workloadId": "",
"networkPolicyId": "f89e80ed-1208-4607-82b2-df2779d90f21",
"id": "f89e80ed-1208-4607-82b2-df2779d90f21/701825869",
"description": "Allow ICMP packets",
"type": "INBOUND",
"source": "0.0.0.0/0",
"action": "INBOUND",
"protocol": "ICMP",
"portRange": ""
},
{
"stackId": "bcc60174-50e6-44e4-bd45-463845124d87",
"workloadId": "6ca53aff-8930-46d6-ba86-afbeb0b46bb7",
"networkPolicyId": "2ac958f2-0976-4de9-95f6-3546fc10f8d0",
"id": "2ac958f2-0976-4de9-95f6-3546fc10f8d0/INBOUND/-812331665/0",
"description": "custom-inbound",
"type": "INBOUND",
"source": "192.168.0.1/32",
"action": "ALLOW",
"protocol": "TCP",
"portRange": "80"
}
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/networkpolicyrules
Retrieve a list of all network policy rules in a given environment.
| Query Params | |
|---|---|
workloadIdstring |
The workload ID to get the network policy rules for. It is optional. |
typestring |
The type of network policy rule, either INBOUND or OUTBOUND. It is optional. |
| Attributes | |
|---|---|
idstring |
The ID of the network policy rule, in the form networkProfileId/type/hashCode/occurrence. |
stackIdUUID |
The UUID of the stack to which the network policy belongs. |
workloadIdUUID |
The UUID of the workload to which the network policy rule is applied. Corresponds to the first workload ID in the network policy's list of instance selectors. |
networkPolicyIdUUID |
The UUID of the network policy to which the network policy rule belongs. |
descriptionstring |
A summary of what this rule does or a name of this rule. It is highly recommended to give a unique description to easily identify a rule. |
typestring |
The type of network policy rule, either INBOUND or OUTBOUND. |
sourcestring |
A subnet that will define all the IPs allowed or denied by this rule. |
actionstring |
The network policy rule action: ALLOW (allow traffic) or BLOCK (deny traffic). |
protocolstring |
Supported protocols are: TCP, UDP, TCP_UDP, ESP, AH, ICMP or GRE. |
portRangestring |
This specifies on which ports traffic will be allowed or denied by this rule. It can be a range of ports separated by a hyphen. |
Retrieve a network policy rule
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/networkpolicyrules/2ac958f2-0976-4de9-95f6-3546fc10f8d0/INBOUND/-812331665/0"
The above command returns a JSON structured like this:
{
"data": {
"stackId": "bcc60174-50e6-44e4-bd45-463845124d87",
"workloadId": "6ca53aff-8930-46d6-ba86-afbeb0b46bb7",
"networkPolicyId": "2ac958f2-0976-4de9-95f6-3546fc10f8d0",
"id": "2ac958f2-0976-4de9-95f6-3546fc10f8d0/INBOUND/-812331665/0",
"description": "custom-inbound",
"type": "INBOUND",
"source": "192.168.0.1/32",
"action": "ALLOW",
"protocol": "TCP",
"portRange": "80"
}
}
GET /services/:service_code/:environment_name/networkpolicyrules/:id
Retrieve a network policy rule in a given environment.
| Attributes | |
|---|---|
idstring |
The ID of the network policy rule, in the form networkProfileId/type/hashCode/occurrence. |
stackIdUUID |
The UUID of the stack to which the network policy belongs. |
workloadIdUUID |
The UUID of the workload to which the network policy rule is applied. Corresponds to the first workload ID in the network policy's list of instance selectors. |
networkPolicyIdUUID |
The UUID of the network policy to which the network policy rule belongs. |
descriptionstring |
A summary of what this rule does or a name of this rule. It is highly recommended to give a unique description to easily identify a rule. |
typestring |
The type of network policy rule, either INBOUND or OUTBOUND. |
sourcestring |
A subnet that will define all the IPs allowed or denied by this rule. |
actionstring |
The network policy rule action: ALLOW (allow traffic) or BLOCK (deny traffic). |
protocolstring |
Supported protocols are: TCP, UDP, TCP_UDP, ESP, AH, ICMP or GRE. |
portRangestring |
This specifies on which ports traffic will be allowed or denied by this rule. It can be a range of ports separated by a hyphen. |
Create a network policy rule
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/networkpolicyrules"
Request body example:
{
"workloadId": "bf9fd2ac-f761-46ef-88e0-b61ef68f8619",
"description": "npr_cloudmc_isk",
"protocol": "TCP",
"type": "INBOUND",
"action": "ALLOW",
"source": "0.0.0.0/0",
"portRange": "8080"
}
POST /services/:service_code/:environment_name/networkpolicyrules
Create a new network policy rule.
| Required | |
|---|---|
workloadIdUUID |
The workload UUID to create a network policy for. |
descriptionstring |
A summary of what this rule does or a name of this rule. It is highly recommended to give a unique description to easily identify a rule. |
protocolstring |
Supported protocols are: TCP, UDP, TCP_UDP, ESP and AH. |
typestring |
The type of network policy rule. Supported types are: INBOUND (Ingress) and OUTBOUND (Egress). |
actionstring |
The network policy rule action: ALLOW (allow traffic) or BLOCK (block traffic). |
sourcestring |
A subnet that will define all the IPs allowed or denied by this rule. |
portRangestring |
This specifies on which ports traffic will be allowed or denied by this rule. It can be a range of ports separated by a hyphen. |
Delete a network policy rule
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stack/razine-test-env/networkpolicyrules/93cf3029-3657-44c4-add1-22c4ee2bcb94/INBOUND/1617554972/0"
DELETE /services/:service_code/:environment_name/networkpolicyrules/:id
Delete a network policy rule.
Edit a network policy rule
curl -X PUT \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/networkpolicyrules/2ac958f2-0976-4de9-95f6-3546fc10f8d0/INBOUND/-812331665/0"
Request body example:
{
"description": "npr_cloudmc_isk",
"workloadId": "6ca53aff-8930-46d6-ba86-afbeb0b46bb7",
"type": "INBOUND",
"source": "192.168.0.1/32",
"action": "ALLOW",
"protocol": "TCP",
"portRange": "80"
}
PUT /services/:service_code/:environment_name/networkpolicyrules/:id
Edit a network policy rule.
| Required | |
|---|---|
descriptionstring |
A summary of what this rule does or a name of this rule. It is highly recommended to give a unique description to easily identify a rule. |
workloadIdUUID |
The UUID of the workload to which the network policy rule is applied. Corresponds to the first workload ID in the network policy's list of instance selectors. |
typestring |
The type of network policy rule. Supported types are: INBOUND (Ingress) and OUTBOUND (Egress). |
sourcestring |
A CIDR subnet that will define all the IPs allowed or denied by this rule. |
actionstring |
The network policy rule action: ALLOW (allow traffic) or BLOCK (deny traffic). |
protocolstring |
Supported protocols are: TCP, UDP, TCP_UDP, ESP or AH. |
portRangestring |
This specifies on which ports traffic will be allowed or denied by this rule. It can be a range of ports separated by a hyphen. Not required for protocol for ESP or AH. |
Edge delivery
Sites
Create and manage your CDN, WAF, and/or Serverless Scripting Delivery sites.
List sites
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/sites"
The above command returns a JSON structured like this:
{
"data": [
{
"stackId": "1415650d-1d02-4097-a79a-8f6e4bb4f483",
"domain": "slow-test.com",
"createdAt": "2021-02-19T19:29:58.713874Z",
"updatedAt": "2021-02-19T19:30:04.656652Z",
"services": [
"CDN",
"SERVERLESS_EDGE_ENGINE",
"WAF"
],
"id": "9ae3717a-006a-4aa7-b64b-8bc8d2f2d6e5",
"status": "ACTIVE"
},
{
"stackId": "1415650d-1d02-4097-a79a-8f6e4bb4f483",
"domain": "speedytest.com",
"createdAt": "2021-02-08T14:57:01.576395Z",
"updatedAt": "2021-02-08T14:57:09.861832Z",
"services": [
"CDN",
"WAF"
],
"id": "04deb6d1-ad84-425f-8f10-92106a22c3b4",
"status": "ACTIVE"
}
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/sites
Retrieve a list of all sites in a given environment.
| Optional | |
|---|---|
statusstring |
Setting the status parameter will return only the stackpath sites with that particular status. The site's status can either be ACTIVE, PENDING, or PROVISIONING. |
| Attributes | |
|---|---|
idstring |
A sites's unique identifier. |
stackIdstring |
The ID of the stack that a site belongs to. |
domainstring |
The domain of the site. |
statusstring |
The status of the site. It can either be ACTIVE, PENDING, or PROVISIONING. |
createdAtstring |
The date on which the site was created. |
updatedAtstring |
The date on which the site was last updated. |
servicesarray |
List of services running on the site. |
Retrieve a site
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/sites/9ae3717a-006a-4aa7-b64b-8bc8d2f2d6e5"
The above command returns a JSON structured like this:
{
"data": {
"stackId": "1415650d-1d02-4097-a79a-8f6e4bb4f483",
"domain": "slow-test.com",
"createdAt": "2021-02-19T19:29:58.713874Z",
"updatedAt": "2021-02-19T19:30:04.656652Z",
"services": [
"CDN",
"SERVERLESS_EDGE_ENGINE",
"WAF"
],
"id": "9ae3717a-006a-4aa7-b64b-8bc8d2f2d6e5",
"status": "ACTIVE",
"edgeAddress": "v2a4k7y8.stackpathcdn.com",
"anycastIp": "151.139.128.10",
"deliveryDomains": [
{
"domain": "v2a4k7y8.stackpathcdn.com",
"validatedAt": "2021-02-26T19:00:15.177411Z"
},
{
"domain": "slow-test.com",
}],
}
}
GET /services/:service_code/:environment_name/sites/:id
Retrieve a site in a given environment.
| Attributes | |
|---|---|
idstring |
A sites's unique identifier. |
stackIdstring |
The ID of the stack that a site belongs to. |
domainstring |
The domain of the site. |
statusstring |
The status of the site. It can either be ACTIVE, PENDING, or PROVISIONING. |
createdAtstring |
The date on which the site was created. |
updatedAtstring |
The date on which the site was last updated. |
servicesarray |
List of services running on the site. |
edgeAddressstring |
The edge address of the site. |
anycastIpstring |
The Anycast IP address that domains should be pointed to. |
deliveryDomainsarray |
List of delivery domains of the site. |
deliveryDomains.domainstring |
A delivery domain of the site. |
deliveryDomains.validatedAtstring |
The date the domain was validated to be pointing to Stackpath. |
Create a site
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/sites"
Request body example for a site with basic authentication:
{
"domain": "www.rpgfan.com",
"services": [
"CDN",
"SERVERLESS_EDGE_ENGINE",
"WAF"
],
"protocol": "HTTPS",
"hostname": "199.250.204.212",
"authMethod": "BASIC",
"username": "alavoie",
"password": "123456"
}
Request body example for a site with no authentication:
{
"domain": "www.rpgfan.com",
"services": [
"CDN",
"SERVERLESS_EDGE_ENGINE",
"WAF"
],
"protocol": "HTTPS",
"hostname": "199.250.204.212"
}
The above commands return a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/sites
Create a site in a given environment.
| Required | |
|---|---|
domainstring |
The domain name that will be used for the site. |
servicesArray[string] |
Services list that will be used on the site. Possibles values are CDN,SERVERLESS_EDGE_ENGINE or WAF. |
protocolstring |
Protocol that will be used to communicate with the hostname. Possibles values are HTTP or HTTPS. |
hostnamestring |
The hostname to that will be used to get the information from. The hostname can be an IP or a name. It may include a specific port and a precise path as well (e.g. 199.250.204.212:80/test). |
| Optional | |
|---|---|
authMethodstring |
The authentication method to communicate with the hostname. Possibles values are NONE or BASIC. If not provided, it will default to NONE unless the username or password is provided. It would then default to BASIC. |
usernameArray[Object] |
The username for the basic authentication. Required if authMethod is BASIC or if the password id provided. |
passwordstring |
The password for the basic authentication. Required if authMethod is BASIC or if the password id provided. |
Delete a site
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/sites/f8ad8351-4f07-4b52-92ec-fd2983873853"
The above command returns a JSON structured like this:
{
"taskId": "57fc8d89-6f13-451b-8b66-fcd96e1fedbd",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/sites/:id
Delete a site in a given environment.
| Attributes | |
|---|---|
taskId string |
The task id related to the site deletion. |
taskStatus string |
The status of the operation. |
Enable CDN
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/sites/f8ad8351-4f07-4b52-92ec-fd2983873853?operation=enable_cdn"
The above command returns a JSON structured like this:
{
"taskId": "57fc8d89-6f13-451b-8b66-fcd96e1fedbd",
"taskStatus": "SUCCESS"
}
POST /services/:service_code/:environment_name/sites/:id?operation=enable_cdn
Enable CDN for a given site.
| Attributes | |
|---|---|
taskId string |
The task id related to the site deletion. |
taskStatus string |
The status of the operation. |
Disable CDN
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/sites/f8ad8351-4f07-4b52-92ec-fd2983873853?operation=disable_cdn"
The above command returns a JSON structured like this:
{
"taskId": "57fc8d89-6f13-451b-8b66-fcd96e1fedbd",
"taskStatus": "SUCCESS"
}
POST /services/:service_code/:environment_name/sites/:id?operation=disable_cdn
Disable CDN for a given site.
| Attributes | |
|---|---|
taskId string |
The task id related to the site deletion. |
taskStatus string |
The status of the operation. |
Enable WAF
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/sites/f8ad8351-4f07-4b52-92ec-fd2983873853?operation=enable_waf"
The above command returns a JSON structured like this:
{
"taskId": "57fc8d89-6f13-451b-8b66-fcd96e1fedbd",
"taskStatus": "SUCCESS"
}
POST /services/:service_code/:environment_name/sites/:id?operation=enable_waf
Enable WAF for a given site.
| Attributes | |
|---|---|
taskId string |
The task id related to the site deletion. |
taskStatus string |
The status of the operation. |
Disable WAF
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/sites/f8ad8351-4f07-4b52-92ec-fd2983873853?operation=disable_waf"
The above command returns a JSON structured like this:
{
"taskId": "57fc8d89-6f13-451b-8b66-fcd96e1fedbd",
"taskStatus": "SUCCESS"
}
POST /services/:service_code/:environment_name/sites/:id?operation=disable_waf
Disable WAF for a given site.
| Attributes | |
|---|---|
taskId string |
The task id related to the site deletion. |
taskStatus string |
The status of the operation. |
Enable Serverless Scripts
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/sites/f8ad8351-4f07-4b52-92ec-fd2983873853?operation=enable_scripts"
The above command returns a JSON structured like this:
{
"taskId": "57fc8d89-6f13-451b-8b66-fcd96e1fedbd",
"taskStatus": "SUCCESS"
}
POST /services/:service_code/:environment_name/sites/:id?operation=enable_scripts
Enable Serverless Scripts for a given site.
| Attributes | |
|---|---|
taskId string |
The task id related to the site deletion. |
taskStatus string |
The status of the operation. |
Disable Serverless Scripts
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/sites/f8ad8351-4f07-4b52-92ec-fd2983873853?operation=disable_scripts"
The above command returns a JSON structured like this:
{
"taskId": "57fc8d89-6f13-451b-8b66-fcd96e1fedbd",
"taskStatus": "SUCCESS"
}
POST /services/:service_code/:environment_name/sites/:id?operation=disable_scripts
Disable Serverless Scripts for a given site.
| Attributes | |
|---|---|
taskId string |
The task id related to the site deletion. |
taskStatus string |
The status of the operation. |
Origin Settings
Retrieve origin settings
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/originsettings/eb3ecdbe-d73b-40e6-a263-166accba75ed"
The above command returns a JSON structured like this:
{
"data": {
"id": "eb3ecdbe-d73b-40e6-a263-166accba75ed",
"stackId": "144c3d16-2879-4286-82b6-75e58a6ec1cb",
"scopeConfigurationId": "45ab2429-ca8d-4145-acc3-f6aea6e8dbef",
"domain": "bluegreen.com",
"webSocketsEnabled": false,
"sslValidationEnabled": false,
"pullProtocol": "MATCH",
"hostHeader": "Host: marvel.com",
"origin": {
"id": "d92531f4-28f5-456d-9b5f-d1cbb17ccfee",
"address": "www.test.com:80",
"commonCertificateName": "commonName",
"authMethod": "BASIC",
"username": "username"
},
"backupOriginEnabled": true,
"backupOriginExcludeCodes": ["415"],
"backupOrigin": {
"id": "f6766ee9-680d-4c92-b77c-36c60a251061",
"address": "1.2.3.4:443/path",
"authMethod": "NONE"
}
}
}
GET /services/:service_code/:environment_name/originsettings/:id
Retrieve origin settings for a site in a given environment.
| Attributes | |
|---|---|
idUUID |
A site's unique identifier. |
stackIdUUID |
The ID of the stack that a site belongs to. |
scopeConfigurationIdUUID |
The ID of the scope of the site that the origins are connected to. |
domainstring |
The domain of the site. |
webSocketsEnabled boolean |
Specifies if web socket connections to the origin server are enabled. |
sslValidationEnabled boolean |
Specifies if SSL validation for the origins is enabled. |
pullProtocol string |
The type of protocol used to pull content from the origin. Must be one of ["HTTP", "HTTPS", "MATCH"]. "MATCH" is equivalent to "HTTP or HTTPS". |
hostHeader string |
The host header to be used to pull content from the origin. "Dynamic" refers to using the requested domain name (Host: %client.request.host%) as the host header. |
origin Object |
The primary origin that the CDN uses to pull content from. |
origin.id UUID |
An origin's unique identifier. |
origin.address string |
The address of the primary origin that the CDN uses to pull content from. Can be a valid IPv4 address or a valid domain name. It may include a specific port and a precise path as well (e.g. 199.250.204.212:80/test). Port must be one of [80, 8080, 443, 1935, 9091]. |
origin.authMethod string |
Specifies the authentication method that the origin uses. Must be one of ["NONE", "BASIC"]. |
origin.username string |
Username to use when authenticating with the origin. |
origin.password string |
Password to use when authenticating with the origin. |
origin.commonCertificateName string |
Common name to validate SSL origin requests against. |
backupOriginEnabledboolean |
Specifies if a backup origin for the site is configured. |
backupOriginExcludeCodes Array[string] |
Requests are made to the backup origin on any 4xx or 5xx response codes returned from the primary origin. This property specifies the response status codes for which calls to the backup origin must not be made. Multiple response codes can be excluded. e.g: ["410", "411", "412"]. Asterisks can be used to cover a range of codes. e.g. All the 4xx codes can be covered using "4*". |
backupOrigin Object |
The secondary origin that the CDN uses to pull content from when the primary origin is not available. |
backupOrigin.id UUID |
A backup origin's unique identifier. |
backupOrigin.address string |
The address of the secondary origin that the CDN uses to pull content from. Can be a valid IPv4 address or a valid domain name. It may include a specific port and a precise path as well (e.g. 199.250.204.212:80/test). Port must be one of [80, 8080, 443, 1935, 9091]. |
backupOrigin.authMethod string |
Specifies the authentication method that the backup origin uses. Must be one of ["NONE", "BASIC"]. |
backupOrigin.username string |
Username to use when authenticating with the backup origin. |
backupOrigin.password string |
Password to use when authenticating with the backup origin. |
backupOrigin.commonCertificateName string |
Common name to validate SSL origin requests against. |
Edit origin settings
curl -X PATCH \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/originsettings/eb3ecdbe-d73b-40e6-a263-166accba75ed"
Request body example:
{
"pullProtocol": "MATCH",
"hostHeader": "marvel.com",
"sslValidationEnabled": true,
"origin": {
"commonCertificateName": "commonName"
},
"backupOriginEnabled": true,
"backupOrigin": {
"address": "1.2.3.4:80"
}
}
The above command returns a JSON structured like this:
{
"taskId": "e94d2bb6-059a-4eb6-a14f-7c596a5fdea6",
"taskStatus": "SUCCESS"
}
PATCH /services/:service_code/:environment_name/originsettings/:id
Edit origin settings for a site in a given environment.
| Optional | |
|---|---|
webSocketsEnabled boolean |
Specifies if web socket connections to the origin server are enabled. |
sslValidationEnabled boolean |
Specifies if SSL validation for the origins is enabled. |
pullProtocol string |
The type of protocol used to pull content from the origin. Must be one of ["HTTP", "HTTPS", "MATCH"]. "MATCH" is equivalent to "HTTP or HTTPS". |
hostHeader string |
The host header to be used to pull content from the origin. "Dynamic" refers to using the requested domain name (Host: %client.request.host%) as the host header. |
origin Object |
The primary origin that the CDN uses to pull content from. |
origin.address string |
The address of the primary origin that the CDN uses to pull content from. Can be a valid IPv4 address or a valid domain name. It may include a specific port and a precise path as well (e.g. 199.250.204.212:80/test). Port must be one of [80, 8080, 443, 1935, 9091]. |
origin.authMethod string |
Specifies the authentication method that the origin uses. Must be one of ["NONE", "BASIC"]. |
origin.username string |
Username to use when authenticating with the origin. |
origin.password string |
Password to use when authenticating with the origin. |
origin.commonCertificateName string |
Common name to validate SSL origin requests against. |
backupOriginEnabledboolean |
Specifies if a backup origin for the site is configured. To configure backupOrigin's settings, this property must be passed as true. |
backupOriginExcludeCodes Array[string] |
Requests are made to the backup origin on any 4xx or 5xx response codes returned from the primary origin. This property specifies the response status codes for which calls to the backup origin must not be made. Multiple response codes can be excluded. e.g: ["410", "411", "412"]. Asterisks can be used to cover a range of codes. e.g. All the 4xx codes can be covered using "4*". |
backupOrigin Object |
The secondary origin that the CDN uses to pull content from when the primary origin is not available. |
backupOrigin.address string |
The address of the secondary origin that the CDN uses to pull content from. Can be a valid IPv4 address or a valid domain name. It may include a specific port and a precise path as well (e.g. 199.250.204.212:80/test). Port must be one of [80, 8080, 443, 1935, 9091]. |
backupOrigin.authMethod string |
Specifies the authentication method that the backup origin uses. Must be one of ["NONE", "BASIC"]. |
backupOrigin.username string |
Username to use when authenticating with the backup origin. |
backupOrigin.password string |
Password to use when authenticating with the backup origin. |
backupOrigin.commonCertificateName string |
Common name to validate SSL origin requests against. |
Delivery domains
Delivery domains allow the CDN to recognize an HTTP request and associate it with a site.
List delivery domains
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/deliverydomains?siteId=439b145a-7c55-4a73-8cf2-d8faabfe6d22"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "439b145a-7c55-4a73-8cf2-d8faabfe6d22/test-domain.com",
"stackId": "3deddcbd-3757-44cf-a4a6-93028fc4649a",
"siteId": "439b145a-7c55-4a73-8cf2-d8faabfe6d22",
"domain": "test-domain.com"
},
{
"id": "439b145a-7c55-4a73-8cf2-d8faabfe6d22/u7f7rXXX.stackpathcdn.com",
"stackId": "3deddcbd-3757-44cf-a4a6-93028fc4649a",
"siteId": "439b145a-7c55-4a73-8cf2-d8faabfe6d22",
"domain": "u7f7rXXX.stackpathcdn.com",
"validatedAt": "2021-02-26T19:00:15.177411Z"
},
{
"id": "439b145a-7c55-4a73-8cf2-d8faabfe6d22/www.test-domain.com",
"stackId": "3deddcbd-3757-44cf-a4a6-93028fc4649a",
"siteId": "439b145a-7c55-4a73-8cf2-d8faabfe6d22",
"domain": "www.test-domain.com"
}
],
"metadata": {
"recordCount": 3
}
}
GET /services/:service_code/:environment_name/deliverydomains?siteId=:siteId
Retrieve a list of all delivery domains in a given environment for a site.
| Query Params | |
|---|---|
siteIdUUID |
The ID of the site for which to list delivery domains. This parameter is required. |
| Attributes | |
|---|---|
idstring |
The delivery domain unique identifier. |
domainstring |
The site's domain name. |
siteIdUUID |
The ID of the site that the delivery domain belongs to. |
stackIdUUID |
The ID of the stack that the site belongs to. |
updatedAtstring |
The date the domain was validated to be pointing to Stackpath. |
Retrieve a delivery domain
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/deliverydomains/439b145a-7c55-4a73-8cf2-d8faabfe6d22/test-domain.com"
The above command returns a JSON structured like this:
{
"data": {
"id": "439b145a-7c55-4a73-8cf2-d8faabfe6d22/test-domain.com",
"stackId": "3deddcbd-3757-44cf-a4a6-93028fc4649a",
"siteId": "439b145a-7c55-4a73-8cf2-d8faabfe6d22",
"domain": "test-domain.com"
}
}
GET /services/:service_code/:environment_name/deliverydomains/:id
Retrieve a delivery domain of a site in a given environment.
| Attributes | |
|---|---|
idstring |
The delivery domain unique identifier. |
domainstring |
The site's domain name. |
siteIdUUID |
The ID of the site that the delivery domain belongs to. |
stackIdUUID |
The ID of the stack that the site belongs to. |
updatedAtstring |
The date the domain was validated to be pointing to Stackpath. |
Delete a delivery domain
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/deliverydomains/439b145a-7c55-4a73-8cf2-d8faabfe6d22/test-domain.com"
The above command returns a JSON structured like this:
{
"taskId": "57fc8d89-6f13-451b-8b66-fcd96e1fedbd",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/deliverydomains/:id
Delete a delivery domain of a site in a given environment.
| Attributes | |
|---|---|
taskId string |
The task id related to the site deletion. |
taskStatus string |
The status of the operation. |
Create a delivery domain
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/deliverydomains?siteId=a2fefb15-7e31-4c72-87e0-5a892e91c8d9"
Request body example:
{
"domain": "new-domain.com",
}
The above command returns a JSON structured like this:
{
"taskId": "57fc8d89-6f13-451b-8b66-fcd96e1fedbd",
"taskStatus": "SUCCESS"
}
POST /services/:service_code/:environment_name/deliverydomains?siteId=:id
Create a delivery domain of a site in a given environment.
| Required | |
|---|---|
domainstring |
The site's domain name. |
| Attributes | |
|---|---|
taskId string |
The task id related to the domain creation. |
taskStatus string |
The status of the operation. |
CDN
Retrieve CDN settings
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/cdnsettings/9f236f19-55db-411f-9f05-bd79dc91a69b"
The above command returns a JSON structured like this:
{
"data": {
"siteId": "9f236f19-55db-411f-9f05-bd79dc91a69b",
"cacheExpirePolicy": "SPECIFY_CDN_TTL",
"cacheTtl": 60,
"queryStringControl": "CUSTOM",
"customCachedQueryStrings": [
"customQuery",
],
"dynamicCachingByHeaderEnabled": true,
"customCachedHeaders": [
"mydynamicheader"
],
"gzipCompressionEnabled": true,
"gzipCompressionLevel": 2,
"contentPersistenceEnabled": true,
"maximumStaleFileTtl": 30,
"varyHeaderEnabled": true,
"browserCacheTtl": 60,
"corsHeaderEnabled": true,
"allowedCorsOrigins": "SPECIFY_ORIGINS",
"originsToAllowCors": [
"example.org"
],
"http2SupportEnabled": true,
"http2ServerPushEnabled": true,
"linkHeader": "my-link-header",
"canonicalHeaderEnabled": true,
"canonicalHeader": "my-canonical-header",
"urlCachingEnabled": true,
"urlCachingTtl": 300
}
}
GET /services/:service_code/:environment_name/cdnsettings/:siteId
Retrieve CDN settings for a site in a given environment.
| Attributes | |
|---|---|
siteIdUUID |
A site's unique identifier. |
cacheExpirePolicyString |
A site's cache expiry policy. Can be ORIGIN_CONTROLLED, SPECIFY_CDN_TTL, NEVER_EXPIRE, or DO_NOT_CACHE. |
cacheTtlInteger |
The time to live for the cache, in seconds. Depends on the cache expiry policy. |
queryStringControlString |
The strategy for caching query strings. Can be IGNORE, CACHE_ALL or CUSTOM. |
customCachedQueryStringsArray[String] |
List of custom cached query strings. Only visible if the queryStringControl attribute is CUSTOM. |
dynamicCachingByHeaderEnabledBoolean |
Whether or not to enable dynamic caching by headers. |
customCachedHeadersArray[String] |
A list of custom cached headers. Only visible if dynamicCachingByHeaderEnabled is true. |
gzipCompressionEnabledBoolean |
Whether or not to enable gzip compression. |
gzipCompressionLevelInteger |
The level for the gzip compression. Values are between 1 to 6. Only visible is gzipCompressionEnabled is true. |
contentPersistenceEnabledBoolean |
Whether or not make cached content available after its expiration time. |
maximumStaleFileTtlInteger |
The maximum time to live for stale files, in seconds. Only visible if contentPersistenceEnabled is true. |
varyHeaderEnabledBoolean |
Whether or not to enable honoring the vary header in a request. |
browserCacheTtlInteger |
Sets the default browser expiration time for cached assets, in seconds. |
corsHeaderEnabledBoolean |
Sets the Access-Control-Allow-Origin header to allow browsers to access this domain from other origins. |
allowedCorsOriginsString |
The strategy for allowing cors origins. Can be SPECIFY_ORIGINS or ALL_ORIGINS. |
originsToAllowCorsArray[String] |
A list of origins to allow cors requests from. Only visible if allowedCorsOrigins is set to SPECIFY_ORIGINS. |
http2SupportEnabledBoolean |
Whether or not to enable supporting applications using HTTP/2 protocol. |
http2ServerPushEnabledBoolean |
Whether or not to push assets to the client or browser (user) in advance (before the user requests these assets) which enables faster load times. |
linkHeaderString |
The link header for http2ServerPush, only visible if http2ServerPushEnabled is true. |
canonicalHeaderEnabledBoolean |
Whether or not to enable setting Link: http://{hostname}/URI; rel="canonical" header on each response. |
canonicalHeaderString |
The hostname for the canonicalHeader, only visible if canonicalHeaderEnabled is true. |
urlCachingEnabledBoolean |
Whether or not to enable caching of URLs without file extensions. |
urlCachingTtlInteger |
The time to live for the url cache. Only visible if urlCachingEnabled is true. |
Edit CDN settings
curl -X PATCH \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/cdnsettings/9f236f19-55db-411f-9f05-bd79dc91a69b"
Request body example:
{
"urlCachingEnabled": true,
"urlCachingTtl": 1,
"canonicalHeaderEnabled": true,
"queryStringControl": "CUSTOM",
"customCachedQueryStrings": [
"help"
]
}
The above command returns a JSON structured like this:
{
"taskId": "e94d2bb6-059a-4eb6-a14f-7c596a5fdea6",
"taskStatus": "SUCCESS"
}
PATCH /services/:service_code/:environment_name/cdnsettings/:siteId
Edit CDN settings for a site in a given environment.
| Optional | |
|---|---|
cacheExpirePolicyString |
A site's cache expiry policy. Can be ORIGIN_CONTROLLED, SPECIFY_CDN_TTL, NEVER_EXPIRE, or DO_NOT_CACHE. |
cacheTtlInteger |
The time to live for the cache, in seconds. Only applies when attribute cacheExpirePolicy is SPECIFY_CDN_TTL. |
queryStringControlString |
The strategy for caching query strings. Can be IGNORE, CACHE_ALL or CUSTOM. |
customCachedQueryStringsArray[String] |
List of custom cached query strings. Only applies when attribute queryStringControl is CUSTOM. |
dynamicCachingByHeaderEnabledBoolean |
Whether or not to enable dynamic caching by headers. |
customCachedHeadersArray[String] |
A list of custom cached headers. Only applies when attribute dynamicCachingByHeaderEnabled is true. |
gzipCompressionEnabledBoolean |
Whether or not to enable gzip compression. |
gzipCompressionLevelInteger |
The level for the gzip compression. Values should be between 1 to 6, where 6 is the default. Only applies when attribute gzipCompressionEnabled is true. |
contentPersistenceEnabledBoolean |
Whether or not make cached content available after its expiration time. |
maximumStaleFileTtlInteger |
The maximum time to live for stale files, in seconds. Only applies when attribute contentPersistenceEnabled is true. |
varyHeaderEnabledBoolean |
Whether or not to enable honoring the vary header in a request. |
browserCacheTtlInteger |
Sets the default browser expiration time for cached assets, in seconds. |
corsHeaderEnabledBoolean |
Sets the Access-Control-Allow-Origin header to allow browsers to access this domain from other origins. |
allowedCorsOriginsString |
The strategy for allowing cors origins. Can be SPECIFY_ORIGINS or ALL_ORIGINS. |
originsToAllowCorsArray[String] |
A list of origins to allow cors requests from. Only applies when attribute allowedCorsOrigins is set to SPECIFY_ORIGINS. |
http2SupportEnabledBoolean |
Whether or not to enable supporting applications using HTTP/2 protocol. |
http2ServerPushEnabled Boolean |
Whether or not to push assets to the client or browser (user) in advance (before the user requests these assets) which enables faster load times. |
linkHeaderString |
The link header for http2ServerPush, only visible if http2ServerPushEnabled is true. |
canonicalHeaderEnabledBoolean |
Whether or not to enable setting Link: http://{hostname}/URI; rel="canonical" header on each response. |
canonicalHeaderString |
The hostname for the canonicalHeader, only applies when attribute canonicalHeaderEnabled is true. |
urlCachingEnabledBoolean |
Whether or not to enable caching of URLs without file extensions. |
urlCachingTtlInteger |
The time to live for the url cache. Only applies when attribute urlCachingEnabled is true. |
Purge all CDN cached content
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/cdnsettings/9f236f19-55db-411f-9f05-bd79dc91a69b?operation=purgeAll"
The above command returns a JSON structured like this:
{
"taskId": "e6c03893-212f-4e28-b7a1-66ed7b554839",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/cdnsettings/:siteId?operation=purgeAll
Purge all CDN cached content of a site in a given environment.
| Attributes | |
|---|---|
taskId string |
The task id related to the purge operation. |
taskStatus string |
The status of the operation. |
Purge custom CDN cached content
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/cdnsettings/9f236f19-55db-411f-9f05-bd79dc91a69b?operation=purge"
Request body example for URL purge type:
{
"purgeType":"URL",
"items": [
{
"url": "http://<domain-name>",
"recursive": true,
"purgeAllDynamic": true,
"headers": [],
"purgeSelector": {
"selectorName": "(?i)<header_name>",
"selectorValue": "<header_value>",
"selectorType": "HEADER",
"selectorValueDelimiter": ""
}
}
]
}
Request body example for PATH purge type:
{
"purgeType":"PATH",
"items": [
{
"url": "/path/to/file",
"recursive": false,
"purgeAllDynamic": false,
"headers": [],
"purgeSelector": {
"selectorName": "(?i)<header_name>",
"selectorValue": "<header_value>",
"selectorType": "HEADER",
"selectorValueDelimiter": ""
}
}
]
}
The above command returns a JSON structured like this:
{
"taskId": "e6c03893-212f-4e28-b7a1-66ed7b554839",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/cdnsettings/:siteId?operation=purge
Purge custom CDN cached content of a site in a given environment.
| Required | |
|---|---|
itemsArray[Object] |
The items to purge from the CDN. |
items.urlString |
The URL or path at which to delete content. |
| Optional | |
|---|---|
purgeTypeString |
The type of cache purge. Can be URL or PATH. Default value is URL. |
items.recursiveBoolean |
Whether or not to recursively delete content from the CDN. |
items.invalidateOnlyBoolean |
Whether or not to mark the asset as expired and re-validate instead of deleting. |
items.purgeAllDynamicBoolean |
Whether or not to purge dynamic versions of assets. |
items.headersArray[String] |
A list of HTTP request headers used to construct a cache key to purge content by. These headers must be configured in the site configuration's DynamicContent.headerFields property. |
items.purgeSelectorArray[Object] |
A key/value pair definition of content to purge from the CDN. |
items.purgeSelector.selectorTypeString |
The kinds of content that can be purged from the CDN. One of: HEADER (Purge content based on an HTTP response header), TAG (Purge content based on an X-TAG HTTP header value. Purging by tag can be useful when content on the origin is tagged). |
items.purgeSelector.selectorNameString |
The name of the type of content to purge. For example, the name of the HTTP response header. Names are case sensitive. |
items.purgeSelector.selectorValueString |
The value of the content to purge. For example, the value of the HTTP response header. Values are case sensitive and may be wild-carded, but cannot match a "/". |
items.purgeSelector.selectorValueDelimiterString |
The delimiter to separate multiple values with. Defaults to ",". |
WAF
Retrieve WAF Settings
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/wafsettings/1b1cd7e6-41ab-4e0f-a59a-5c4b89da1b36"
The above command returns a JSON structured like this:
{
"data": {
"id": "1b1cd7e6-41ab-4e0f-a59a-5c4b89da1b36",
"stackId": "1415650d-1d02-4097-a79a-8f6e4bb4f483",
"domain": "site.com",
"apiUrls": [
"/test/this/way"
],
"ddosSettings": {
"globalThreshold": 5000,
"burstThreshold": 110,
"subSecondBurstThreshold": 50
},
"monitoringEnabled": false,
"owaspThreats": {
"sqlInjection": false,
"xssAttack": true,
"shellShockAttack": true,
"remoteFileInclusion": true,
"apacheStrutsExploit": true,
"localFileInclusion": false,
"commonWebApplicationVulnerabilities": true,
"webShellExecutionAttempt": true,
"protocolAttack": true,
"csrf": true,
"openRedirect": false,
"shellInjection": false,
"codeInjection": false,
"sensitiveDataExposure": false,
"xmlExternalEntity": false,
"personalIdentifiableInfo": false,
"serverSideTemplateInjection": false
},
"generalPolicies": {
"blockInvalidUserAgents": false,
"blockUnknownUserAgents": true,
"httpMethodValidation": true
},
"trafficSources": {
"viaTorNodes": true,
"viaProxyNetworks": true,
"viaHostingServices": true,
"viaVpn": true,
"convictedBotTraffic": true,
"trafficFromSuspiciousNatRanges": true,
"externalReputationBlockList": false,
"trafficViaCDN": true
},
"antiAutomationBotProtection": {
"forceBrowserValidationOnTrafficAnomalies": true,
"challengeAutomatedClients": false,
"challengeHeadlessBrowsers": false,
"antiScraping": false
},
"behavioralWaf": {
"spamProtection": true,
"blockProbingAndForcedBrowsing": true,
"obfuscatedAttacksAndZeroDayMitigation": true,
"repeatedViolations": true,
"bruteForceProtection": true
},
"cmsProtection": {
"wordpressWafRuleset": false,
"whiteListWordpress": false,
"whiteListModx": false,
"whiteListDrupal": false,
"whiteListJoomla": false,
"whiteMagento": false,
"whiteListOriginIp": true,
"whiteListUmbraco": false,
"whiteListPimcore": true
},
"allowKnownBots": {
"Internet Archive Bot": true
}
}
}
GET /services/:service_code/:environment_name/wafsettings/:siteId
Retrieve WAF Settings for a site in a given environment.
| Attributes | |
|---|---|
idstring |
The ID of the site that the WAF settings belongs to. |
stackIdstring |
The ID of the stack that a site belongs to. |
domainstring |
The domain of the site. |
ddosSettingsobject |
The DDoS Setting containing the different threshold values. |
ddosSettings.globalThresholdInteger |
The number of overall requests per ten seconds that can trigger DDoS protection. |
ddosSettings.burstThresholdInteger |
The number of requests per two seconds that can trigger DDoS protection. |
ddosSettings.subSecondBurstThresholdInteger |
The number of requests per 0.1 seconds that can trigger DDoS protection. |
apiUrlsarray |
List of configured API urls. |
monitoringEnabledboolean |
If the monitoring mode is enabled. |
owaspThreatsobject |
StackPath’s core rule set & OWASP’s most critical Web application security risks. |
owaspThreats.sqlInjectionboolean |
Block requests suspected of being a SQL injection attack attempt. SQL injection attacks attempt to exploit vulnerabilities in a Web application's code and seek to gain access and control over the database. A successful attack would typically result in stolen data or the site being defaced or taken down. |
owaspThreats.xssAttackboolean |
Block requests suspected of being a Cross-Site-Scripting attack attempt. Cross Site Scripting attacks attempt to exploit vulnerabilities in a Web application and seek to inject a client side script either across an entire site or to a specific user's session. A successful attack would typically allow forbidden access to a user's actions and data. |
owaspThreats.shellShockAttackboolean |
Block requests suspected of being a Shellshock attack attempt. A Shellshock attack is an attempt to exploit a server's vulnerabilities to gain full access and control over them. A successful attack would typically either abuse a server's resources or hack the website. |
owaspThreats.remoteFileInclusionboolean |
Block requests suspected of being a Remote File Inclusion attempt. Remote File Inclusion attempts to exploit vulnerabilities in a Web application (typically in PHP) to execute a script from a 3rd party server. RFI attacks provide a backdoor for the hacker to change the behaviour of a server and Web application. |
owaspThreats.apacheStrutsExploitboolean |
Patch known vulnerabilities in the Apache Struts framework by blocking requests suspected of exploiting these vulnerabilities. |
owaspThreats.localFileInclusionboolean |
Block requests suspected of a Local File Inclusion attempt. Local File Inclusion attempts seek to exploit vulnerabilities in a Web application to execute potentially harmful scripts on your servers. |
owaspThreats.commonWebApplicationVulnerabilitiesboolean |
Block attempts to access and potentially harm your servers through common backdoors, such as common control panels, configuration scripts etc. which may be accessible to unwanted users. |
owaspThreats.webShellExecutionAttemptboolean |
Block requests suspected of Web shell attempts. A Web shell is a script that can be uploaded to a Web server to enable remote administration of the machine. Infected Web servers can either be internet-facing or internal to the network, where the Web shell is used to further pivot to internal hosts. |
owaspThreats.protocolAttackboolean |
Block requests suspected of being a protocol attack attempt. Protocol attacks attempt to inject and manipulate headers or query parameters via insufficient user input sanitation. |
owaspThreats.csrfboolean |
StackPath WAF will generate a CSRF token that is added to forms. Requests without a valid CSRF token will be blocked. |
owaspThreats.openRedirectboolean |
Block requests suspected of being an Open Redirect attempt. Open Redirect attempts to exploit vulnerabilities in a Web application to redirect a user to a new website without any validation of the target of redirect. |
owaspThreats.shellInjectionboolean |
Block requests suspected of being a shell injection attack attempt. Shell Injection is an attack in which the goal is execution of arbitrary commands on the host operating system via a vulnerable application. Command injection attacks are possible when an application passes unsafe user supplied data (forms, cookies, HTTP headers etc.) to a system shell. |
owaspThreats.codeInjectionboolean |
Block requests suspected of being a code injection attack attempt. Code injection is the general term for attack types which consist of injecting code that is then interpreted/executed by the application. This type of attack exploits poor handling of untrusted data. |
owaspThreats.sensitiveDataExposureboolean |
Block requests that do not properly protect sensitive data. |
owaspThreats.xmlExternalEntityboolean |
Block requests that are potentially an XML external entity injection attack. |
owaspThreats.personalIdentifiableInfoboolean |
Block requests that do not properly protect personally identifiable information (PII). |
owaspThreats.serverSideTemplateInjectionboolean |
Block requests that are potentially a server-side template injection attack. |
generalPoliciesobject |
General policies |
generalPolicies.blockInvalidUserAgentsboolean |
Block requests in which the HTTP header describing the user-agent (browser and platform) seems invalid and cannot be translated to a known legitimate browser. Automated processes (bots) are most likely to have invalid user agents. |
generalPolicies.blockUnknownUserAgentsboolean |
Block requests in which the HTTP header describing the user-agent (browser and platform) is missing. |
generalPolicies.httpMethodValidationboolean |
Block non-standard and suspicious HTTP methods. |
trafficSourcesobject |
Real-time threat intelligence for IP addresses, source location, and information on malicious IPs. |
trafficSources.viaTorNodesboolean |
Challenge traffic from The Onion Ring exit nodes to block bots and known bad devices. While TOR is used sometimes purely for Web anonymity, it is commonly used by hackers, scrapers, and spammers to crawl or hack Web applications. |
trafficSources.viaProxyNetworksboolean |
Challenge traffic from any known proxy network to block bots and known bad devices. While proxy services are used sometimes purely for Web anonymity, they are also commonly used by hackers, scrapers, and spammers to crawl or hack Web applications. |
trafficSources.viaHostingServicesboolean |
Challenge traffic from IP addresses known to be of hosting service companies. This rule is unlikely to see legitimate human traffic on these IP spaces since they are typically used for server hosting. In most cases, traffic from these IP spaces originate from infected servers that are controlled by hackers. |
trafficSources.viaVpnboolean |
Challenge traffic from any known VPN to block bots and known bad devices. While VPNs are sometimes used purely for Web anonymity, they are also commonly used by hackers, scrapers, and spammers to crawl or hack Web applications. |
trafficSources.convictedBotTrafficboolean |
Challenge traffic from IP addresses that have been convicted of automated activities (bots) on this site or on others. These IP addresses are used by malicious automated agents while no legitimate traffic has been observed on them. |
trafficSources.trafficFromSuspiciousNatRangesboolean |
Challenge traffic from high-risk NAT ranges, based on historical web behavior detected by a machine learning classifier. |
trafficSources.externalReputationBlockListboolean |
Challenge traffic from any known spammer or abuser, based on data from multiple services. |
trafficSources.trafficViaCDNboolean |
Challenge traffic from IP addresses originating from CDN companies. |
antiAutomationBotProtectionobject |
Block automated traffic from scanning and browsing your online application. |
antiAutomationBotProtection.forceBrowserValidationOnTrafficAnomaliesboolean |
Challenge and block requests if the user or device behind them does not keep session cookies and does not execute JavaScripts correctly. Most malicious automated activities (bots) do not meet these conditions and will, therefore, effectively be blocked by the JavaScript challenge triggered in any suspected situation. Clients can also be blocked depending on whether they act in an abnormal to the specific domain—by scraping content in a way that most sessions on this domain don't—or clients that try to, for example, avoid detection by switching IPs. |
antiAutomationBotProtection.challengeAutomatedClientsboolean |
Captcha-challenge and block sessions conducted by standard Web browsers if there is evidence that these sessions are being automated and not driven by a human user. Such automation is used primarily for screen scraping and other very targeted, site-specific malicious automation. |
antiAutomationBotProtection.challengeHeadlessBrowsersboolean |
Challenge requests if the user or device behind them uses an automation tool that initiates browsers but is actually an automation tool without real display—such as phantomJS, Selenium, or other. While such tools are favored by programmers, they are also extremely popular with scrapers, hackers and even in sophisticated DDoS attacks to circumvent standard anti-bot measures. |
antiAutomationBotProtection.antiScrapingboolean |
A more hardened anti-automation policy that is meant to stop scrapers by using faster and harsher convictions. |
cmsProtectionobject |
Whitelist admin users. |
cmsProtection.wordpressWafRulesetboolean |
Enable a set of rules designed to block common Wordpress exploits. |
cmsProtection.whiteListWordpressboolean |
Enable whitelist WordPress admin logged-in users. |
cmsProtection.whiteListModxboolean |
Enable whitelist MODX admin logged-in users. |
cmsProtection.whiteListDrupalboolean |
Enable whitelist Drupal admin logged-in users. |
cmsProtection.whiteListJoomlaboolean |
Enable whitelist Joomla admin logged-in users. |
cmsProtection.whiteMagentoboolean |
Enable whitelist Magento admin logged-in users. |
cmsProtection.whiteListOriginIpboolean |
Enable this policy to whitelist requests coming from the origin for plugin updates and general CMS updates, |
cmsProtection.whiteListUmbracoboolean |
Enable whitelist Umbraco admin logged-in users. |
cmsProtection.whiteListPimcoreboolean |
Enable whitelist PimCore admin logged-in users. |
behavioralWafobject |
StackPath's sophisticated user behaviour and reputation analysis rules. |
behavioralWaf.spamProtectionboolean |
Challenge and block user sessions and activities that seem to be aggressively using forms on your website to post spam content, generate new accounts, and more. Also, require a handshake (if not already provided) to clients making POST requests. |
behavioralWaf.blockProbingAndForcedBrowsingboolean |
Challenge or block sessions and users that seem to make brute-forced requests on random URLs seeking to discover a Web application's structure and hidden directories. |
behavioralWaf.obfuscatedAttacksAndZeroDayMitigationboolean |
Block clients performing multiple injection attacks. |
behavioralWaf.repeatedViolationsboolean |
Challenge or block clients that failed to answer previous challenges. |
behavioralWaf.bruteForceProtectionboolean |
Challenge and block attempts seeking to guess user names and passwords on Web login forms. |
allowKnownBotsobject |
An object containing known bots. |
Edit WAF Settings
curl -X PATCH \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/wafsettings/c0ddc1b3-b390-4f39-b200-5c0323ca306e"
Request body example:
{
"owaspThreats": {
"localFileInclusion": false
}
}
The above command returns a JSON structured like this:
{
"taskId": "573ca8fa-c5ad-4b19-a315-8ddbbc78d7c0",
"taskStatus": "SUCCESS"
}
PATCH /services/:service_code/:environment_name/wafsettings/:siteId
Edit the WAF settings for a site in a given environment.
| Attributes | |
|---|---|
ddosSettingsobject |
The DDoS Setting containing the different threshold values. |
ddosSettings.globalThresholdInteger |
The number of overall requests per ten seconds that can trigger DDoS protection. |
ddosSettings.burstThresholdInteger |
The number of requests per two seconds that can trigger DDoS protection. |
ddosSettings.subSecondBurstThresholdInteger |
The number of requests per 0.1 seconds that can trigger DDoS protection. |
apiUrlsarray |
List of configured API urls. |
monitoringEnabledboolean |
If the monitoring mode is enabled. |
owaspThreatsobject |
StackPath’s core rule set & OWASP’s most critical Web application security risks. |
owaspThreats.sqlInjectionboolean |
Block requests suspected of being a SQL injection attack attempt. SQL injection attacks attempt to exploit vulnerabilities in a Web application's code and seek to gain access and control over the database. A successful attack would typically result in stolen data or the site being defaced or taken down. |
owaspThreats.xssAttackboolean |
Block requests suspected of being a Cross-Site-Scripting attack attempt. Cross Site Scripting attacks attempt to exploit vulnerabilities in a Web application and seek to inject a client side script either across an entire site or to a specific user's session. A successful attack would typically allow forbidden access to a user's actions and data. |
owaspThreats.shellShockAttackboolean |
Block requests suspected of being a Shellshock attack attempt. A Shellshock attack is an attempt to exploit a server's vulnerabilities to gain full access and control over them. A successful attack would typically either abuse a server's resources or hack the website. |
owaspThreats.remoteFileInclusionboolean |
Block requests suspected of being a Remote File Inclusion attempt. Remote File Inclusion attempts to exploit vulnerabilities in a Web application (typically in PHP) to execute a script from a 3rd party server. RFI attacks provide a backdoor for the hacker to change the behaviour of a server and Web application. |
owaspThreats.apacheStrutsExploitboolean |
Patch known vulnerabilities in the Apache Struts framework by blocking requests suspected of exploiting these vulnerabilities. |
owaspThreats.localFileInclusionboolean |
Block requests suspected of a Local File Inclusion attempt. Local File Inclusion attempts seek to exploit vulnerabilities in a Web application to execute potentially harmful scripts on your servers. |
owaspThreats.commonWebApplicationVulnerabilitiesboolean |
Block attempts to access and potentially harm your servers through common backdoors, such as common control panels, configuration scripts etc. which may be accessible to unwanted users. |
owaspThreats.webShellExecutionAttemptboolean |
Block requests suspected of Web shell attempts. A Web shell is a script that can be uploaded to a Web server to enable remote administration of the machine. Infected Web servers can either be internet-facing or internal to the network, where the Web shell is used to further pivot to internal hosts. |
owaspThreats.protocolAttackboolean |
Block requests suspected of being a protocol attack attempt. Protocol attacks attempt to inject and manipulate headers or query parameters via insufficient user input sanitation. |
owaspThreats.csrfboolean |
StackPath WAF will generate a CSRF token that is added to forms. Requests without a valid CSRF token will be blocked. |
owaspThreats.openRedirectboolean |
Block requests suspected of being an Open Redirect attempt. Open Redirect attempts to exploit vulnerabilities in a Web application to redirect a user to a new website without any validation of the target of redirect. |
owaspThreats.shellInjectionboolean |
Block requests suspected of being a shell injection attack attempt. Shell Injection is an attack in which the goal is execution of arbitrary commands on the host operating system via a vulnerable application. Command injection attacks are possible when an application passes unsafe user supplied data (forms, cookies, HTTP headers etc.) to a system shell. |
owaspThreats.codeInjectionboolean |
Block requests suspected of being a code injection attack attempt. Code injection is the general term for attack types which consist of injecting code that is then interpreted/executed by the application. This type of attack exploits poor handling of untrusted data. |
owaspThreats.sensitiveDataExposureboolean |
Block requests that do not properly protect sensitive data. |
owaspThreats.xmlExternalEntityboolean |
Block requests that are potentially an XML external entity injection attack. |
owaspThreats.personalIdentifiableInfoboolean |
Block requests that do not properly protect personally identifiable information (PII). |
owaspThreats.serverSideTemplateInjectionboolean |
Block requests that are potentially a server-side template injection attack. |
generalPoliciesobject |
General policies |
generalPolicies.blockInvalidUserAgentsboolean |
Block requests in which the HTTP header describing the user-agent (browser and platform) seems invalid and cannot be translated to a known legitimate browser. Automated processes (bots) are most likely to have invalid user agents. |
generalPolicies.blockUnknownUserAgentsboolean |
Block requests in which the HTTP header describing the user-agent (browser and platform) is missing. |
generalPolicies.httpMethodValidationboolean |
Block non-standard and suspicious HTTP methods. |
trafficSourcesobject |
Real-time threat intelligence for IP addresses, source location, and information on malicious IPs. |
trafficSources.viaTorNodesboolean |
Challenge traffic from The Onion Ring exit nodes to block bots and known bad devices. While TOR is used sometimes purely for Web anonymity, it is commonly used by hackers, scrapers, and spammers to crawl or hack Web applications. |
trafficSources.viaProxyNetworksboolean |
Challenge traffic from any known proxy network to block bots and known bad devices. While proxy services are used sometimes purely for Web anonymity, they are also commonly used by hackers, scrapers, and spammers to crawl or hack Web applications. |
trafficSources.viaHostingServicesboolean |
Challenge traffic from IP addresses known to be of hosting service companies. This rule is unlikely to see legitimate human traffic on these IP spaces since they are typically used for server hosting. In most cases, traffic from these IP spaces originate from infected servers that are controlled by hackers. |
trafficSources.viaVpnboolean |
Challenge traffic from any known VPN to block bots and known bad devices. While VPNs are sometimes used purely for Web anonymity, they are also commonly used by hackers, scrapers, and spammers to crawl or hack Web applications. |
trafficSources.convictedBotTrafficboolean |
Challenge traffic from IP addresses that have been convicted of automated activities (bots) on this site or on others. These IP addresses are used by malicious automated agents while no legitimate traffic has been observed on them. |
trafficSources.trafficFromSuspiciousNatRangesboolean |
Challenge traffic from high-risk NAT ranges, based on historical web behavior detected by a machine learning classifier. |
trafficSources.externalReputationBlockListboolean |
Challenge traffic from any known spammer or abuser, based on data from multiple services. |
trafficSources.trafficViaCDNboolean |
Challenge traffic from IP addresses originating from CDN companies. |
antiAutomationBotProtectionobject |
Block automated traffic from scanning and browsing your online application. |
antiAutomationBotProtection.forceBrowserValidationOnTrafficAnomaliesboolean |
Challenge and block requests if the user or device behind them does not keep session cookies and does not execute JavaScripts correctly. Most malicious automated activities (bots) do not meet these conditions and will, therefore, effectively be blocked by the JavaScript challenge triggered in any suspected situation. Clients can also be blocked depending on whether they act in an abnormal to the specific domain—by scraping content in a way that most sessions on this domain don't—or clients that try to, for example, avoid detection by switching IPs. |
antiAutomationBotProtection.challengeAutomatedClientsboolean |
Captcha-challenge and block sessions conducted by standard Web browsers if there is evidence that these sessions are being automated and not driven by a human user. Such automation is used primarily for screen scraping and other very targeted, site-specific malicious automation. |
antiAutomationBotProtection.challengeHeadlessBrowsersboolean |
Challenge requests if the user or device behind them uses an automation tool that initiates browsers but is actually an automation tool without real display—such as phantomJS, Selenium, or other. While such tools are favored by programmers, they are also extremely popular with scrapers, hackers and even in sophisticated DDoS attacks to circumvent standard anti-bot measures. |
antiAutomationBotProtection.antiScrapingboolean |
A more hardened anti-automation policy that is meant to stop scrapers by using faster and harsher convictions. |
cmsProtectionobject |
Whitelist admin users. |
cmsProtection.wordpressWafRulesetboolean |
Enable a set of rules designed to block common Wordpress exploits. |
cmsProtection.whiteListWordpressboolean |
Enable whitelist WordPress admin logged-in users. |
cmsProtection.whiteListModxboolean |
Enable whitelist MODX admin logged-in users. |
cmsProtection.whiteListDrupalboolean |
Enable whitelist Drupal admin logged-in users. |
cmsProtection.whiteListJoomlaboolean |
Enable whitelist Joomla admin logged-in users. |
cmsProtection.whiteMagentoboolean |
Enable whitelist Magento admin logged-in users. |
cmsProtection.whiteListOriginIpboolean |
Enable this policy to whitelist requests coming from the origin for plugin updates and general CMS updates, |
cmsProtection.whiteListUmbracoboolean |
Enable whitelist Umbraco admin logged-in users. |
cmsProtection.whiteListPimcoreboolean |
Enable whitelist PimCore admin logged-in users. |
behavioralWafobject |
StackPath's sophisticated user behaviour and reputation analysis rules. |
behavioralWaf.spamProtectionboolean |
Challenge and block user sessions and activities that seem to be aggressively using forms on your website to post spam content, generate new accounts, and more. Also, require a handshake (if not already provided) to clients making POST requests. |
behavioralWaf.blockProbingAndForcedBrowsingboolean |
Challenge or block sessions and users that seem to make brute-forced requests on random URLs seeking to discover a Web application's structure and hidden directories. |
behavioralWaf.obfuscatedAttacksAndZeroDayMitigationboolean |
Block clients performing multiple injection attacks. |
behavioralWaf.repeatedViolationsboolean |
Challenge or block clients that failed to answer previous challenges. |
behavioralWaf.bruteForceProtectionboolean |
Challenge and block attempts seeking to guess user names and passwords on Web login forms. |
allowKnownBotsobject |
An object containing known bots. |
Firewall Rules
Deploy and manage Firewall Rules used to control and limit access to your sites.
List firewall rules
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/firewallrules?siteId=0a57855b-26d8-4e8f-8b77-429997c7c5fb"
The above command returns a JSON structured like this:
{
"data": [
{
"action": "ALLOW",
"enabled": "true",
"id": "1533148",
"ipEnd": "20.20.20.20",
"ipStart": "10.10.10.10",
"name": "Rule 1 ",
"siteId": "0a57855b-26d8-4e8f-8b77-429997c7c5fb"
},
{
"action": "BLOCK",
"enabled": "true",
"id": "1533345",
"ipEnd": "192.1.1.2",
"ipStart": "192.0.0.1",
"name": "Rule 2 ",
"siteId": "0a57855b-26d8-4e8f-8b77-429997c7c5fb"
}
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/firewallrules?siteId=:siteId
| Query Params | |
|---|---|
actionstring |
Filter IP addresses, which are either ALLOW or BLOCK. This parameter is optional. If not provided, it will return both the type of IP addresses. |
siteIdUUID |
The ID of the site for which the firewall rule is applied to. This parameter is required. |
| Attributes | |
|---|---|
actionstring |
Either ALLOW or BLOCK. |
enabledboolean |
Whether or not the rule is enabled. |
idstring |
The unique identifier for the rule. |
ipEndstring |
The end ip adress for the rule. |
ipStartstring |
The start ip adress for the rule. |
namestring |
The name of the rule. |
siteIdUUID |
The ID of the site for which the firewall rule is applied to. |
Retrieve a firewall rule
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/firewallrules/1533148?siteId=0a57855b-26d8-4e8f-8b77-429997c7c5fb"
The above command returns a JSON structured like this:
{
"data":{
"action": "ALLOW",
"enabled": "true",
"id": "1533148",
"ipEnd": "20.20.20.20",
"ipStart": "10.10.10.10",
"name": "Rule 1 ",
"siteId": "0a57855b-26d8-4e8f-8b77-429997c7c5fb"
},
}
GET /services/:service_code/:environment_name/firewallrules/:id?siteId=:siteId
| Query Params | |
|---|---|
siteIdUUID |
The ID of the site for which the firewall rule is applied to. This parameter is required. |
| Attributes | |
|---|---|
actionstring |
Either ALLOW or BLOCK. |
enabledboolean |
Whether or not the rule is enabled. |
idstring |
The unique identifier for the rule. |
ipEndstring |
The end ip adress for the rule. |
ipStartstring |
The start ip adress for the rule. |
namestring |
The name of the rule. |
siteIdUUID |
The ID of the site for which the firewall rule is applied to. |
Create a firewall rule
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/firewallrules?siteId=f9dea588-d7ab-4f42-b6e6-4b85f273f3db"
Request body example for creating a firewall rule:
{
"action": "ALLOW",
"enabled": true,
"ipEnd": "192.168.0.7",
"ipStart": "192.168.0.6",
"name": "firewall rule",
"siteId": "1c6c127a-bfa4-4c85-a329-13c0581b41eb"
}
The above commands return a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/firewallrules?siteId=:siteId
Restrict access to a site using allow and block rules.
| Query Params | |
|---|---|
siteIdUUID |
The ID of the site for which to create the firewall rule. This parameter is required. |
| Required | |
|---|---|
actionstring |
Either ALLOW or BLOCK. |
ipStartstring |
The start ip adress for the rule. When no ipEnd attribute is provided, the rule only applies for the ip provided in ipStart. |
namestring |
The name of the rule. |
| Optional | |
|---|---|
enabledboolean |
Whether or not the rule is enabled. The default value is false. |
ipEndstring |
The end ip adress for the rule. |
siteIdUUID |
The ID of the site for which the firewall rule is applied to. |
Edit a firewall rule
curl -X PUT \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/firewallrules/1576836?siteId=1c6c127a-bfa4-4c85-a329-13c0581b41eb"
Request body example:
{
"action": "ALLOW",
"enabled": true,
"id": "1576836",
"ipEnd": "192.1.1.2",
"ipStart": "192.0.0.1",
"name": "allow.rule.cloudmc.xzp12",
"siteId": "1c6c127a-bfa4-4c85-a329-13c0581b41eb"
}
The above commands return a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/firewallrules/:id?siteId=:siteId
Edit a firewall rule.
| Query Params | |
|---|---|
siteIdUUID |
The ID of the site for which the firewall rule is applied to. This parameter is required. |
| Required | |
|---|---|
actionstring |
Either ALLOW or BLOCK. |
ipStartstring |
The start ip adress for the rule. |
namestring |
The name of the rule. |
| Optional | |
|---|---|
enabledboolean |
Whether or not the rule is enabled. The default value is false. |
idstring |
The unique identifier for the rule. |
ipEndstring |
The end ip adress for the rule. |
siteIdUUID |
The ID of the site for which the firewall rule is applied to. |
Delete a firewall rule
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/firewallrules/2318483?siteId=0a57855b-26d8-4e8f-8b77-429997c7c5fb"
The above command returns a JSON structured like this:
{
"taskId": "ef70cafa-0544-4709-a66a-c68595ee105a",
"taskStatus": "SUCCESS"
}
DELETE /services/:service_code/:environment_name/firewallrules/:id?siteId=:siteId
Delete a firewall rule
| Query Params | |
|---|---|
siteIdUUID |
The ID of the site for which to delete the firewall rule. This parameter is required. |
The following attributes are returned as part of the response.
| Attributes | |
|---|---|
taskId string |
The task id related to the firewall rule deletion. |
taskStatus string |
The status of the operation. |
Scripts
Deploy and manage Serverless Scripts used to interact with requests made to the site.
List scripts
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/scripts?siteId=0a57855b-26d8-4e8f-8b77-429997c7c5fb"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "4d13a920-79b7-4129-957b-bd4f006b1ac8",
"stackId": "87e22df5-cac9-4e42-9b75-02996af95566",
"siteId": "0a57855b-26d8-4e8f-8b77-429997c7c5fb",
"name": "scriptName",
"createdAt": "2021-03-15T19:05:45.157987Z",
"updatedAt": "2021-03-15T19:05:45.157987Z",
"version": "1",
"routes": [
"v1/api"
]
},
{
"id": "28e6b0c7-ee5d-4bd3-abfb-13dfc6e15c0d",
"stackId": "87e22df5-cac9-4e42-9b75-02996af95566",
"siteId": "0a57855b-26d8-4e8f-8b77-429997c7c5fb",
"name": "scriptName2",
"createdAt": "2021-03-15T18:53:18.587749Z",
"updatedAt": "2021-03-15T18:53:18.587749Z",
"version": "1",
"routes": [
"v1/api",
"v2/api"
]
}
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/scripts?siteId=:siteId
| Query Params | |
|---|---|
siteIdUUID |
The ID of the site for which to list the scripts. This parameter is required. |
| Attributes | |
|---|---|
idUUID |
The unique identifier for the script. |
stackIdUUID |
The ID of the stack that the script belongs to. |
siteIdUUID |
The ID of the site that the script belongs to. |
namestring |
The display name of the script. |
createdAtstring |
Creation timestamp of the script. |
updatedAtstring |
The date on which the script was last updated. |
versionstring |
The version number of the script. |
routesArray[string] |
The routes that incoming requests should respond with a script. |
Retrieve a script
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/scripts/439b145a-7c55-4a73-8cf2-d8faabfe6d22?siteId=0a57855b-26d8-4e8f-8b77-429997c7c5fb"
The above command returns a JSON structured like this:
{
"data": {
"id": "4d13a920-79b7-4129-957b-bd4f006b1ac8",
"stackId": "87e22df5-cac9-4e42-9b75-02996af95566",
"siteId": "0a57855b-26d8-4e8f-8b77-429997c7c5fb",
"name": "scriptName1",
"createdAt": "2021-03-15T19:05:45.157987Z",
"updatedAt": "2021-03-15T19:05:45.157987Z",
"code": "// sample script
addEventListener('fetch', event => {
event.respondWith(handleRequest(event.request));
});
/**
* Fetch and return the request body
* @param {Request} request
*/
async function handleRequest(request) {
// Wrap your script in a try/catch and return the error stack to view error information
try {
/* The request can be modified here before sending it with fetch */
const response = await fetch(request);
/* The response can be modified here before returning it */
return response;
} catch (e) {
return new Response(e.stack || e, { status: 500 });
}
}",
"version": "1",
"routes": [
"v1/api"
]
}
}
GET /services/:service_code/:environment_name/scripts/:id?siteId=:siteId
| Query Params | |
|---|---|
siteIdUUID |
The ID of the site for which to list the scripts. This parameter is required. |
Retrieve a script of a site in a given environment.
| Attributes | |
|---|---|
idUUID |
The unique identifier for the script. |
stackIdUUID |
The ID of the stack that the script belongs to. |
siteIdUUID |
The ID of the site that the script belongs to. |
namestring |
The display name of the script. |
createdAtstring |
Creation timestamp of the script. |
updatedAtstring |
The date on which the script was last updated. |
codestring |
The contents of the script. |
versionstring |
The version number of the script. |
routesArray[string] |
The routes that incoming requests should respond with a script. |
Create a script
Create a new serverless script that allows you to run JavaScript code at the Edge, on all of PoPs with real-time access to each of the requests that come in for your site.
POST /services/:service_code/:environment_name/scripts?siteId=:siteId
| Query Params | |
|---|---|
siteIdUUID |
The ID of the site for which to create the script. This parameter is required. |
| Required | |
|---|---|
namestring |
The name of the script. |
routesArray[string] |
At least one route in the form of a URI. |
codestring |
The JavaScript code used for the script. |
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/scripts?siteId=:siteId"
Request body example for creating a script:
{
"siteId": "0a57855b-26d8-4e8f-8b77-429997c7c5fb",
"name": "script-name",
"routes": ["route"],
"code": "// sample script
addEventListener('fetch', event => {
event.respondWith(handleRequest(event.request));
});
/**
* Fetch and return the request body
* @param {Request} request
*/
async function handleRequest(request) {
// Wrap your script in a try/catch and return the error stack to view error information
try {
/* The request can be modified here before sending it with fetch */
const response = await fetch(request);
/* The response can be modified here before returning it */
return response;
} catch (e) {
return new Response(e.stack || e, { status: 500 });
}
}"
}
The above command returns a JSON structured like this:
{
"taskId": "dfc0b899-ac0f-447b-8f50-74bf78d1c034",
"taskStatus": "PENDING"
}
The following attributes are returned as part of the response.
| Attributes | |
|---|---|
taskId string |
The task id related to creation of the script. |
taskStatus string |
The status of the operation. |
Edit a script
Edit a script in a given environment for a given site ID.
curl -X PUT \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/scripts/dd207010-4570-43ee-9ff2-5421d2306b41?siteId=0a57855b-26d8-4e8f-8b77-429997c7c5fb"
Request body example for editing a script:
{
"routes": ["route"],
"code": "console.log('hello')"
}
The above command returns a JSON structured like this:
{
"taskId": "ef70cafa-0544-4709-a66a-c68595ee105a",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/scripts/:id?siteId=:siteId
| Query Params | |
|---|---|
siteIdUUID |
The ID of the site for which to edit the script. This parameter is required. |
| Optional | |
|---|---|
routesArray[string] |
At least one route in the form of a URI. |
codestring |
The JavaScript code used for the script or the Base64 encoded contents of the script |
The following attributes are returned as part of the response.
| Attributes | |
|---|---|
taskId string |
The task id related to creation of the script. |
taskStatus string |
The status of the operation. |
Delete a script
Delete a script in a given environment for a given site ID.
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/scripts/dd207010-4570-43ee-9ff2-5421d2306b41?siteId=0a57855b-26d8-4e8f-8b77-429997c7c5fb"
The above command returns a JSON structured like this:
{
"taskId": "ef70cafa-0544-4709-a66a-c68595ee105a",
"taskStatus": "SUCCESS"
}
DELETE /services/:service_code/:environment_name/scripts/:id?siteId=:siteId
| Query Params | |
|---|---|
siteIdUUID |
The ID of the site for which to delete the script. This parameter is required. |
The following attributes are returned as part of the response.
| Attributes | |
|---|---|
taskId string |
The task id related to the script deletion. |
taskStatus string |
The status of the operation. |
EdgeSSL
EdgeSSL Settings
View and manage SSL settings.
Retrieve EdgeSSL settings
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/edgesslsettings/eb3ecdbe-d73b-40e6-a263-166accba75ed"
The above command returns a JSON structured like this:
{
"data": {
"id": "eb3ecdbe-d73b-40e6-a263-166accba75ed",
"forceHttps": true,
"minTlsVersion": "V1_2"
}
}
GET /services/:service_code/:environment_name/edgesslsettings/:id
Retrieve the EdgeSSL settings for a site in a given environment.
| Attributes | |
|---|---|
idUUID |
A site's unique identifier. |
forceHttpsboolean |
Whether the site redirects all visitors to use HTTPS instead of HTTP. |
minTlsVersionstring |
The minimum TLS version clients must have to access the application. |
Edit EdgeSSL settings
curl -X PATCH \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/edgesslsettings/eb3ecdbe-d73b-40e6-a263-166accba75ed"
The above command returns a JSON structured like this:
{
"forceHttps": "true",
"minTlsVersion": "V1_2"
}
PATCH /services/:service_code/:environment_name/edgesslsettings/:id
Edit the EdgeSSL settings for a site in a given environment.
| Attributes | |
|---|---|
forceHttpsboolean |
Whether the site redirects all visitors to use HTTPS instead of HTTP. |
minTlsVersionstring |
The minimum TLS version clients must have to access the application. |
One or both of these attributes can be updated at the same time.
Certificates
Add Secure Socket Layer (SSL) features to a site.
List certificates
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/certificates?siteId=0a57855b-26d8-4e8f-8b77-429997c7c5fb"
The above command returns a JSON structured like this:
json { "data": [ { "id": "2a12237d-c388-4c19-bff1-b019b837e8f1", "issuer": "Let's Encrypt", "caBundle": "-----BEGIN CERTIFICATE----- MIIEZTCCA02gAwIBAgIQQAF1BIMUpMghjISpDBbN3zANBgkqhkiG9w0BAQsFADA/ MSQwIgY...", "status": "failed", "expiresAt": "2021-04-01T18:11:11.903458Z", "commonName": "helloworld.com", "createdAt": "2021-04-01T18:11:11.904285Z", "isManaged": true, "trusted": false, "updatedAt": "2021-04-04T18:30:32.021842Z" } ], "metadata": { "recordCount": 1 } }
GET /services/:service_code/:environment_name/certificates?siteId=:siteId
| Query Params | |
|---|---|
siteIdUUID |
The ID of the site for which the certificate is applied to. This parameter is required. |
| Attributes | |
|---|---|
idUUID |
The unique identifier of the certificate. |
siteIdUUID |
The unique identifier of the site for which the certificate is applied to. |
issuerstring |
The authority who issued the certificate. |
caBundlestring |
A PEM PKCS #7 formatted certificate authority bundle. |
statusstring |
A SSL certificate status. |
expiresAtstring |
The date the certificate will expire and the status updated to EXPIRED. |
commonNamestring |
A certificate's common name, or the primary domain name the certificate is used for. |
createdAtstring |
The date the certificate was created. |
updatedAtstring |
The last time a certificate was updated by the provisioning process. |
isManagedboolean |
Whether a certificate is managed by StackPath or the end user. |
trustedboolean |
Whether or not the certificate's authority is trusted by a web browser. |
List of possible values for the status attribute:
status |
|
|---|---|
UNKNOWN |
StackPath is unable to determine the certificate's status. This is the default status for end-user provided certificates. |
PENDING |
The certificate is provisioning. |
EXPIRED |
The certificate has expired. |
FAILED |
The certificate failed to provision. |
PENDING_VERIFICATION |
The certificate is pending domain verification by the end user. |
ACTIVE |
The certificate is valid and is in use by one or more hosts. |
INACTIVE |
The certificate is valid but is not in use by any hosts. |
Retrieve a certificate
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/certificates/2a12237d-c388-4c19-bff1-b019b837e8f1?siteId=0a57855b-26d8-4e8f-8b77-429997c7c5fb"
The above command returns a JSON structured like this:
json { "data": { "id": "2a12237d-c388-4c19-bff1-b019b837e8f1", "issuer": "Let's Encrypt", "caBundle": "-----BEGIN CERTIFICATE----- MIIEZTCCA02gAwIBAgIQQAF1BIMUpMghjISpDBbN3zANBgkqhkiG9w0BAQsFADA/ MSQwIgY...", "status": "failed", "expiresAt": "2021-04-01T18:11:11.903458Z", "commonName": "helloworld.com", "createdAt": "2021-04-01T18:11:11.904285Z", "isManaged": true, "trusted": false, "updatedAt": "2021-04-04T18:30:32.021842Z" } }
GET /services/:service_code/:environment_name/certificates/:id?siteId=:siteId
| Query Params | |
|---|---|
siteIdUUID |
The ID of the site for which the certificate is applied to. This parameter is required. |
| Attributes | |
|---|---|
idUUID |
The unique identifier of the certificate. |
siteIdUUID |
The unique identifier of the site for which the certificate is applied to. |
issuerstring |
The authority who issued the certificate. |
caBundlestring |
A PEM PKCS #7 formatted certificate authority bundle. |
statusstring |
A SSL certificate status. |
expiresAtstring |
The date the certificate will expire and the status updated to EXPIRED. |
commonNamestring |
A certificate's common name, or the primary domain name the certificate is used for. |
createdAtstring |
The date the certificate was created. |
updatedAtstring |
The last time a certificate was updated by the provisioning process. |
isManagedboolean |
Whether a certificate is managed by StackPath or the end user. |
trustedboolean |
Whether or not the certificate's authority is trusted by a web browser. |
List of possible values for the status attribute:
status |
|
|---|---|
UNKNOWN |
StackPath is unable to determine the certificate's status. This is the default status for end-user provided certificates. |
PENDING |
The certificate is provisioning. |
EXPIRED |
The certificate has expired. |
FAILED |
The certificate failed to provision. |
PENDING_VERIFICATION |
The certificate is pending domain verification by the end user. |
ACTIVE |
The certificate is valid and is in use by one or more hosts. |
INACTIVE |
The certificate is valid but is not in use by any hosts. |
Create a certificate
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/certificates?siteId=f9dea588-d7ab-4f42-b6e6-4b85f273f3db"
Request body example for creating a certificate:
{
"certificate": "-----BEGIN CERTIFICATE----- X509 certificate content -----END CERTIFICATE-----",
"key": "-----BEGIN PRIVATE KEY----- Private key of the certificate -----END PRIVATE KEY-----",
"caBundle": "-----BEGIN CERTIFICATE----- Certificate authority bundle -----END CERTIFICATE-----"
}
The above commands return a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/certificates?siteId=:siteId
Create a certificate that will automatically be assigned to the site based on the hostnames of the certificate.
| Query Params | |
|---|---|
siteIdUUID |
The ID of the site. This parameter is required. |
| Required | |
|---|---|
certificatestring |
The X509 certificate. |
keystring |
The private key of the certificate. |
| Optional | |
|---|---|
caBundlestring |
The certificate authority bundle. |
The following attributes are returned as part of the response.
| Attributes | |
|---|---|
taskId string |
The task id related to creation of the certificate. |
taskStatus string |
The status of the operation. |
Request a certificate
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/certificates?operation=request&siteId=f9dea588-d7ab-4f42-b6e6-4b85f273f3db"
Request body example for requesting a certificate:
{
"hosts": [
{"domain": "helloworld.com"},
{"domain": "www.helloworld.com"}
],
"verificationMethod": "DNS"
}
The above commands return a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/certificates?operation=request&siteId=:siteId
Request a certificate that will automatically be assigned to the site.
| Query Params | |
|---|---|
siteIdUUID |
The ID of the site. This parameter is required. |
| Required | |
|---|---|
verificationMethodEnum |
The verification method used to validate a requested certificate on a site. Possible values are: DNS and HTTP. |
| Optional | |
|---|---|
hostsArray[string] |
A list of delivery domains that will be included as subject alternative names on the certificate. If no hosts are provided, all delivery domains on the site will be included with the first one in the list being used as the common name. If hosts are provided, the first entry will be used as the common name. If the first host in the list is over 63 characters the shortest host provided will be used as the common name. |
The following attributes are returned as part of the response.
| Attributes | |
|---|---|
taskId string |
The task id related to creation of the certificate. |
taskStatus string |
The status of the operation. |
Delete a certificate
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/certificates/2318483?siteId=6f6c1724-c306-433c-9e09-95227edc7c6c"
The above command returns a JSON structured like this:
{
"taskId": "ef70cafa-0544-4709-a66a-c68595ee105a",
"taskStatus": "SUCCESS"
}
DELETE /services/:service_code/:environment_name/certificates/:id?siteId=:siteId
Delete a certificate.
| Query Params | |
|---|---|
siteIdUUID |
The ID of the site for which to delete the certificate. This parameter is required. |
The following attributes are returned as part of the response.
| Attributes | |
|---|---|
taskId string |
The task id related to the certificate deletion. |
taskStatus string |
The status of the operation. |
EdgeRules
Predefined EdgeRules
The predefined EdgeRules let you configure how StackPath responds to requests to your website. These predefined EdgeRules only work with domains that resolve to StackPath.
List predefined EdgeRules
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/predefinededgerules/dcc2771d-a524-4f8c-a666-f699985d6961"
The above command returns a JSON structured like this:
{
"data": {
"allowEmptyReferrer": false,
"forceWwwEnabled": true,
"id": "c988cc62-24e7-4850-9a81-95f51af0a68e",
"pseudoStreamingEnabled": true,
"referrerList": [
"cloudmc.io",
"saas.cloudmc.io"
],
"referrerProtectionEnabled": true,
"robotsTxtEnabled": true,
"robotsTxtFile": "User-agent: *\nDisallow:",
"scopeId": "e9e48610-3ba6-471a-96f4-7cf18cb73455",
"stackId": "1f259d02-db66-4a93-8402-a0725a00a02a",
}
}
GET /services/:service_code/:environment_name/predefinededgerules/:siteId
Retrieve the configuration of all predefined EdgeRules in a given environment within a site.
| Attributes | |
|---|---|
allowEmptyReferrerboolean |
Whether or not empty referrer is allowed. |
forceWwwEnabledboolean |
Whether or not redirecting every request to a www subdomain is enabled. |
idUUID |
This ID is same as the siteId to which the predefined EdgeRules belong. |
pseudoStreamingEnabledboolean |
Whether or not seeking random locations within MP4 or FLV files without downloading the entire video is enabled. |
referrerListArray[string] |
The list of domains authorized to access content from the site's root scope. Wildcards can be used to specify multiple websites hosted on the same domain. |
referrerProtectionEnabledboolean |
Whether or not referrer protection is enabled. This rule is used to allow only requests whose referrer header matches a URL that you specified. |
robotsTxtEnabledboolean |
Whether or not custom robot.txt support is enabled. This rule is used to configure which pages or files search engine crawlers can or cannot index from the site. |
robotsTxtFilestring |
This field represents the robots.txt file contents. NOTE: When you first enable the robotsTxtEnabled rule, by default, the robots.txt will populate with a rule to disallow all indexing for CDN content. Any change made with this rule will override the contents of the robots.txt file on origin server. |
scopeIdUUID |
The ID of the CDN site's root scope that the predefined rules belongs to. |
stackIdUUID |
The ID of the stack that the predefined rules belong to. |
Edit a predefined EdgeRules
curl -X PATCH \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/predefinededgerules/dcc2771d-a524-4f8c-a666-f699985d6961"
Request body example:
{
"allowEmptyReferrer": true,
"forceWwwEnabled": true,
"pseudoStreamingEnabled": true,
"referrerList": [
"cloudmc.com",
"saas.cloudmc.com"
],
"referrerProtectionEnabled": true,
"robotsTxtEnabled": true,
"robotsTxtFile": "User-agent: *\nDisallow:",
}
The above commands return a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
PATCH /services/:service_code/:environment_name/predefinededgerules/:siteId
| Optional | |
|---|---|
allowEmptyReferrerboolean |
Whether or not empty referrer is allowed. |
forceWwwEnabledboolean |
Whether or not redirecting every request to a www subdomain is enabled. |
pseudoStreamingEnabledboolean |
Whether or not seeking random locations within MP4 or FLV files without downloading the entire video is enabled. |
referrerListArray[string] |
The list of domains authorized to access content from the site's root scope. Wildcards can be used to specify multiple websites hosted on the same domain. |
referrerProtectionEnabledboolean |
Whether or not referrer protection is enabled. This rule is used to allow only requests whose referrer header matches a URL that you specified. |
robotsTxtEnabledboolean |
Whether or not custom robot.txt support is enabled. |
robotsTxtFilestring |
This field represents the robots.txt file contents. NOTE: To update the robotsTxtFile content, the robotsTxtEnabled flag should be included in the request payload. |
Custom Rules
Manage custom rules used to control and limit access to your sites.
List custom rules
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/customrules?siteId=0a57855b-26d8-4e8f-8b77-429997c7c5fb"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "1580676",
"stackId": "7fbea2c0-17d0-41df-b0b1-4d5c95cXXX",
"siteId": "0a57855b-26d8-4e8f-8b77-429997c7c5fb",
"name": "testrequestrate",
"notes": "test-note",
"type": "WAF",
"enabled": true,
"action": "BLOCK",
"actionDuration": "0s",
"statusCode": "FORBIDDEN_403",
"conditions": [
{
"type": "IP",
"operation": "EQUAL",
"value": "120.1.1.1"
}
]
},
{
"id": "1580692",
"stackId": "7fbea2c0-17d0-41df-b0b1-4d5c95cXXX",
"siteId": "0a57855b-26d8-4e8f-8b77-429997c7c5fb",
"name": "testipwafrule",
"notes": "",
"type": "REQUEST_RATE",
"enabled": true,
"action": "ALLOW",
"actionDuration": "0s",
"statusCode": "TOO_MANY_REQUESTS_429",
"nbRequest": 20,
"duration": 60,
"pathRegExp": "/",
"httpMethods": [],
"ipAddresses": []
}
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/customrules?siteId=:siteId
| Query Params | |
|---|---|
siteIdUUID |
The ID of the site for which the custom rule is applied to. This parameter is required. |
| Attributes | |
|---|---|
idstring |
The unique identifier for the rule. |
stackIdUUID |
The ID of the stack for which the custom rule is applied to. |
siteIdUUID |
The ID of the site for which the custom rule is applied to. |
namestring |
The name of the rule. |
notesstring |
The description notes of the rule. |
typestring |
Type of custom rule. One of REQUEST_RATE or WAF. The fields returned are different based on the type, REQUEST_RATE will not return a list of conditions. |
enabledboolean |
Whether or not the rule is enabled. |
actionstring |
Action to be taken when the rule is met. Possible values are ALLOW, BLOCK, CAPTCHA,HANDSHAKE or MONITOR. |
actionDurationstring |
How long a rule's block action will apply to subsequent requests in case of the action BLOCK. Format is a string with a integer followed by the unit (s for seconds, m for minutes and h for hours e.g. 30s). Default is 0s |
statusCodestring |
A custom HTTP status code that the WAF returns if a rule blocks a request. Possible values are FORBIDDEN_403 and TOO_MANY_REQUESTS_429. Default is FORBIDDEN_403. |
nbRequestlong |
Number of dynamic page requests made for the rule to trigger. Only for rule of type REQUEST_RATE. |
durationlong |
Number of seconds that the WAF measures incoming requests over for the rule to trigger. Only for rule of type REQUEST_RATE. |
pathRegExpstring |
The regex expression present in the path for the rule to trigger. Only for rule of type REQUEST_RATE. |
httpMethodsArray[string] |
List of HTTP methods that the rule will apply to. Only for rule of type REQUEST_RATE. Possible values are: GET, POST, PUT, DELETE, HEAD, PATCH, OPTION, CONNECT, TRACE. |
ipAddressesArray[string] |
List of IP addresses that the rule will apply to. Only for rule of type REQUEST_RATE. |
conditionsArray[Object] |
The conditions required for the WAF engine to trigger the rule. All conditions must pass for the rule to trigger. Only for rule of type WAF. |
conditions.typestring |
Type of condition, one of: IP, IP_RANGE, URL, USER_AGENT, HEADER, HTTP_METHOD, FILE_EXTENSION, CONTENT_TYPE, COUNTRY or ORGANIZATION. |
conditions.operationstring |
Operation of the condition, one of:
|
conditions.headerstring |
Value of the header. Only for condition of type HEADER. |
conditions.valuestring |
Value for which the condition holds. |
conditions.endValuestring |
Second value of the condition. Only for condition of type IP_RANGE. |
Retrieve a custom rule
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/customrules/1580676?siteId=0a57855b-26d8-4e8f-8b77-429997c7c5fb"
The above command returns a JSON structured like this:
{
"data": {
"id": "1580676",
"stackId": "7fbea2c0-17d0-41df-b0b1-4d5c95cXXX",
"siteId": "0a57855b-26d8-4e8f-8b77-429997c7c5fb",
"name": "testrequestrate",
"notes": "test-note",
"type": "WAF",
"enabled": true,
"action": "BLOCK",
"actionDuration": "0s",
"statusCode": "FORBIDDEN_403",
"conditions": [
{
"type": "IP",
"operation": "EQUAL",
"value": "120.1.1.1"
}
]
}
}
GET /services/:service_code/:environment_name/customrules/:id?siteId=:siteId
| Query Params | |
|---|---|
siteIdUUID |
The ID of the site for which the custom rule is applied to. This parameter is required. |
| Attributes | |
|---|---|
idstring |
The unique identifier for the rule. |
stackIdUUID |
The ID of the stack for which the custom rule is applied to. |
siteIdUUID |
The ID of the site for which the custom rule is applied to. |
namestring |
The name of the rule. |
notesstring |
The description notes of the rule. |
typestring |
Type of custom rule. One of REQUEST_RATE or WAF. The fields returned are different based on the type, REQUEST_RATE will not return a list of conditions. |
enabledboolean |
Whether or not the rule is enabled. |
actionstring |
Action to be taken when the rule is met. Possible values are ALLOW, BLOCK, CAPTCHA,HANDSHAKE or MONITOR. |
actionDurationstring |
How long a rule's block action will apply to subsequent requests in case of the action BLOCK. Format is a string with a integer followed by the unit (s for seconds, m for minutes and h for hours e.g. 30s). Default is 0s |
statusCodestring |
A custom HTTP status code that the WAF returns if a rule blocks a request. Possible values are FORBIDDEN_403 and TOO_MANY_REQUESTS_429. Default is FORBIDDEN_403. |
nbRequestlong |
Number of dynamic page requests made for the rule to trigger. Only for rule of type REQUEST_RATE. |
durationlong |
Number of seconds that the WAF measures incoming requests over for the rule to trigger. Only for rule of type REQUEST_RATE. |
pathRegExpstring |
The regex expression present in the path for the rule to trigger. Only for rule of type REQUEST_RATE. |
httpMethodsArray[string] |
List of HTTP methods that the rule will apply to. Only for rule of type REQUEST_RATE. Possible values are: GET, POST, PUT, DELETE, HEAD, PATCH, OPTION, CONNECT, TRACE. |
ipAddressesArray[string] |
List of IP addresses that the rule will apply to. Only for rule of type REQUEST_RATE. |
conditionsArray[Object] |
The conditions required for the WAF engine to trigger the rule. All conditions must pass for the rule to trigger. Only for rule of type WAF. |
conditions.typestring |
Type of condition, one of: IP, IP_RANGE, URL, USER_AGENT, HEADER, HTTP_METHOD, FILE_EXTENSION, CONTENT_TYPE, COUNTRY or ORGANIZATION. |
conditions.operationstring |
Operation of the condition, one of:
|
conditions.headerstring |
Value of the header. Only for condition of type HEADER. |
conditions.valuestring |
Value for which the condition holds. |
conditions.endValuestring |
Second value of the condition. Only for condition of type IP_RANGE. |
Create a custom rule
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/customrules?siteId=0a57855b-26d8-4e8f-8b77-429997c7c5fb"
Request body example for a custom rule with conditions:
{
"name": "firewall.allow",
"notes": "some firewall note",
"type": "WAF",
"action": "BLOCK",
"actionDuration": "0s",
"statusCode": "FORBIDDEN_403",
"conditions": [
{
"type": "IP",
"operation": "EQUAL",
"value": "120.1.1.1"
}
]
}
Request body example for a custom role with request rate:
{
"name": "firewall.deny",
"notes": "Deny rule",
"type": "REQUEST_RATE",
"action": "BLOCK",
"actionDuration": "0s",
"statusCode": "TOO_MANY_REQUESTS_429",
"nbRequest": 20,
"duration": 60,
"pathRegExp": "/",
"httpMethods": ["GET"],
"ipAddresses": ["192.168.2.1"]
}
The above commands return a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/customrules?siteId=:siteId
Create a custom rule for a site in a given environment.
| Query Params | |
|---|---|
siteIdUUID |
The ID of the site for which the custom rule is applied to. This parameter is required. |
| Required | |
|---|---|
namestring |
The name of the rule. |
typestring |
Type of custom rule. One of REQUEST_RATE or WAF. The fields returned are different based on the type, REQUEST_RATE will not return a list of conditions. |
actionstring |
Action to be taken when the rule is met. Possible values are ALLOW, BLOCK, CAPTCHA,HANDSHAKE or MONITOR. |
nbRequestlong |
Number of dynamic page requests made for the rule to trigger. Only for rule of type REQUEST_RATE. |
durationlong |
Number of seconds that the WAF measures incoming requests over for the rule to trigger. Only for rule of type REQUEST_RATE. |
conditionsArray[Object] |
The conditions required for the WAF engine to trigger the rule. All conditions must pass for the rule to trigger. Only for rule of type WAF. |
conditions.typestring |
Type of condition, one of: IP, IP_RANGE, URL, USER_AGENT, HEADER, HTTP_METHOD, FILE_EXTENSION, CONTENT_TYPE, COUNTRY or ORGANIZATION. |
conditions.operationstring |
Operation of the condition, one of:
|
conditions.headerstring |
Value of the header. Only for condition of type HEADER. |
conditions.valuestring |
Value for which the condition holds. |
conditions.endValuestring |
Second value of the condition. Only for condition of type IP_RANGE. |
| Optional | |
|---|---|
notesstring |
The description notes of the rule. |
actionDurationstring |
How long a rule's block action will apply to subsequent requests in case of the action BLOCK. Format is a string with a integer followed by the unit (s for seconds, m for minutes and h for hours e.g. 30s). Default is 0s |
statusCodestring |
A custom HTTP status code that the WAF returns if a rule blocks a request. Possible values are FORBIDDEN_403 and TOO_MANY_REQUESTS_429. Default is FORBIDDEN_403. |
pathRegExpstring |
The regex expression that the path must match for the rule to trigger. Default is '/'. Only for rule of type REQUEST_RATE. |
httpMethodsArray[string] |
List of HTTP methods that the rule will apply to. Only for rule of type REQUEST_RATE. |
ipAddressesArray[string] |
List of IP addresses that the rule will apply to. Only for rule of type REQUEST_RATE. |
Create a WAF rule based on a request made to an existing site
POST "https://cloudmc_endpoint/api/v2/services/{serviceCode}/{environment}/wafrequests/{wafrequestId}?operation=create_rule&siteId={siteId}"
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/stackpath-aaaa/env-1/wafrequests/197d190d415bea5ea1385a0de6f3bceb-452444?operation=create_rule&siteId=5ea00192-30f0-4da0-b9d9-461baa3dde89"
Request body example for the custom rule:
{
"action": "MONITOR",
"clientIp": "66.249.82.90"
}
The above commands return a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
| Path Params | |
|---|---|
serviceCodestring |
The globally unique serviceCode that identifies the service connection. |
wafrequestIdUUID |
The ID of the WAF request made to the site. The WAF rule created must map to an existing request made to the site. |
environmentUUID |
The name of the environment containing the site. |
| Query Params | |
|---|---|
operationstring |
The operation executed. This must be create_rule. |
siteIdUUID |
The ID of the site for which the custom rule is applied to. This parameter is required. |
| Required | |
|---|---|
actionstring |
The action to be taken on the provided IP address. The action must be one of ALLOW, BLOCK, MONITOR, CAPTCHA, or HANDSHAKE. |
clientIpstring |
The IP address the WAF request specified was made from. |
Edit a custom rule
curl -X PUT \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/customrules/1576836?siteId=1c6c127a-bfa4-4c85-a329-13c0581b41eb"
Request body example for a custom rule with conditions:
{
"name": "firewalldeny",
"notes": "Deny rule",
"type": "WAF",
"enabled": false,
"action": "BLOCK",
"actionDuration": "10s",
"statusCode": "FORBIDDEN_403",
"conditions": [
{
"type": "IP",
"operation": "EQUAL",
"value": "172.16.254.14"
}
]
}
Request body example for a custom role with request rate:
{
"name": "firewalldeny",
"notes": "Deny rule",
"type": "REQUEST_RATE",
"action": "BLOCK",
"actionDuration": "0s",
"statusCode": "TOO_MANY_REQUESTS_429",
"nbRequest": 20,
"duration": 60,
"pathRegExp": "/",
"httpMethods": ["GET"],
"ipAddresses": ["192.168.2.1"]
}
The above commands returns a JSON structured like this:
{
"taskId": "8fcf30b0-1644-474d-b150-ac0c6f51bf98",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/customrules/:id?siteId=:siteId
Edit a custom rule.
| Query Params | |
|---|---|
siteIdUUID |
The ID of the site for which the custom rule is applied to. This parameter is required. |
| Required | |
|---|---|
namestring |
The name of the rule. |
typestring |
Type of custom rule. One of REQUEST_RATE or WAF. The fields returned are different based on the type, REQUEST_RATE will not return a list of conditions. |
actionstring |
Action to be taken when the rule is met. Possible values are ALLOW, BLOCK, CAPTCHA,HANDSHAKE or MONITOR. |
nbRequestlong |
Number of dynamic page requests made for the rule to trigger. Only for rule of type REQUEST_RATE. |
durationlong |
Number of seconds that the WAF measures incoming requests over for the rule to trigger. Only for rule of type REQUEST_RATE. |
conditionsArray[Object] |
The conditions required for the WAF engine to trigger the rule. All conditions must pass for the rule to trigger. Only for rule of type WAF. |
conditions.typestring |
Type of condition, one of: IP, IP_RANGE, URL, USER_AGENT, HEADER, HTTP_METHOD, FILE_EXTENSION, CONTENT_TYPE, COUNTRY or ORGANIZATION. |
conditions.operationstring |
Operation of the condition, one of:
|
conditions.headerstring |
Value of the header. Only for condition of type HEADER. |
conditions.valuestring |
Value for which the condition holds. |
conditions.endValuestring |
Second value of the condition. Only for condition of type IP_RANGE. |
| Optional | |
|---|---|
notesstring |
The description notes of the rule. |
actionDurationstring |
How long a rule's block action will apply to subsequent requests in case of the action BLOCK. Format is a string with a integer followed by the unit (s for seconds, m for minutes and h for hours e.g. 30s). Default is 0s |
statusCodestring |
A custom HTTP status code that the WAF returns if a rule blocks a request. Possible values are FORBIDDEN_403 and TOO_MANY_REQUESTS_429. Default is FORBIDDEN_403. |
pathRegExpstring |
The regex expression that the path must match for the rule to trigger. Default is '/'. Only for rule of type REQUEST_RATE. |
httpMethodsArray[string] |
List of HTTP methods that the rule will apply to. Only for rule of type REQUEST_RATE. |
ipAddressesArray[string] |
List of IP addresses that the rule will apply to. Only for rule of type REQUEST_RATE. |
Delete a custom rule
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/customrules/1585477?siteId=1b1cd7e6-41ab-4e0f-a59a-5c4b89da1b36"
The above command returns a JSON structured like this:
{
"taskId": "c39f0c66-04a0-40cf-aa2e-485f50a27561",
"taskStatus": "SUCCESS"
}
DELETE /services/:service_code/:environment_name/customrules/:id?siteId=:siteId
Delete a custom rule
| Query Params | |
|---|---|
siteIdUUID |
The ID of the site for which to delete the custom rule. This parameter is required. |
The following attributes are returned as part of the response.
| Attributes | |
|---|---|
taskId string |
The task id related to the custom rule deletion. |
taskStatus string |
The status of the operation. |
Enable a custom rule
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/customrules/1585477?siteId=1b1cd7e6-41ab-4e0f-a59a-5c4b89da1b36&operation=enable"
The above command returns a JSON structured like this:
{
"taskId": "57fc8d89-6f13-451b-8b66-fcd96e1fedbd",
"taskStatus": "SUCCESS"
}
POST /services/:service_code/:environment_name/customrules/:id?siteId=:siteId&operation=enable
| Query Params | |
|---|---|
siteIdUUID |
The ID of the site for which the rule belongs to. This parameter is required. |
The following attributes are returned as part of the response.
| Attributes | |
|---|---|
taskId string |
The task id related to the operation. |
taskStatus string |
The status of the operation. |
Disable a custom rule
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/customrules/1585477?siteId=1b1cd7e6-41ab-4e0f-a59a-5c4b89da1b36&operation=disable"
The above command returns a JSON structured like this:
json { "taskId": "57fc8d89-6f13-451b-8b66-fcd96e1fedbd", "taskStatus": "SUCCESS" }
POST /services/:service_code/:environment_name/customrules/:id?siteId=:siteId&operation=disable
| Query Params | |
|---|---|
siteIdUUID |
The ID of the site for which the rule belongs to. This parameter is required. |
The following attributes are returned as part of the response.
| Attributes | |
|---|---|
taskId string |
The task id related to the operation. |
taskStatus string |
The status of the operation. |
Delivery Rules
Set up delivery rules to improve access, security and set custom rules.
List delivery rules
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/deliveryrules?siteId=dcc2771d-a524-4f8c-a666-f699985d6961"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "fc72c60a-d411-4b35-9deb-9dbc889faf7e",
"name": "addHeader",
"slug": "portal-ui-custom-1617310238955",
"stackId": "fd157f7c-e5cd-439b-b6c5-5864583a8ce8",
"siteId": "dcc2771d-a524-4f8c-a666-f699985d6961"
},
{
"id": "d411c60a-d411-4b35-9deb-f699985d6961",
"name": "removeHeader",
"slug": "portal-ui-custom-1617310238955",
"stackId": "fd157f7c-e5cd-439b-b6c5-5864583a8ce8",
"siteId": "dcc2771d-a524-4f8c-a666-f699985d6961"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/deliveryrules?siteId=:siteId
Retrieve a list of all delivery rules in a given environment within a site.
| Attributes | |
|---|---|
idUUID |
A delivery rule's unique identifier. |
namestring |
The name of the delivery rule. |
slugstring |
A delivery rule's programmatic name. |
stackIdstring |
The ID of the stack that the delivery rule belongs to. |
siteIdstring |
The ID of the site that the delivery rule is applied to. |
Create a delivery rule
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/deliveryrules?siteId=f9dea588-d7ab-4f42-b6e6-4b85f273f3db"
Request body example for creating a delivery rule:
{
"name": "rule",
"conditions": [
{
"trigger": "HEADER",
"operator": "MATCHES",
"target": "my-header"
}],
"actions": [
{
"actionType": "REDIRECT",
"redirectUrl": "https://my-url.com"
}]
}
The above commands return a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/deliveryrules?siteId=:siteId
| Query Params | |
|---|---|
siteIdUUID |
The ID of the site for which to create the delivery rule. This parameter is required. |
| Required | |
|---|---|
namestring |
The name of the delivery rule. |
conditionsArray[Condition] |
At least one condition. |
actionsArray[Action] |
At least one action. |
Update a delivery rule
curl -X PUT \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/deliveryrules/d065db45-1eba-4c62-a017-d51f2d473d4a?siteId=f9dea588-d7ab-4f42-b6e6-4b85f273f3db"
Request body example for updating a delivery rule:
{
"conditions": [
{
"trigger": "HEADER",
"operator": "MATCHES",
"target": "my-header"
}],
"actions": [
{
"actionType": "REDIRECT",
"redirectUrl": "https://my-url.com"
}]
}
The above commands return a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/deliveryrules/:ruleId?siteId=:siteId
| Query Params | |
|---|---|
siteIdUUID |
The ID of the site for which to update the delivery rule. This parameter is required. |
| Required | |
|---|---|
conditionsArray[Condition] |
At least one condition. |
actionsArray[Action] |
At least one action. |
Delete a delivery rule
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/deliveryrules/90d6a6ed-05a5-4b45-8d5a-e8229f535149?siteId=1c6c127a-bfa4-4c85-a329-13c0581b41eb"
The above command returns a JSON structured like this:
{
"taskId": "2c7429dc-64c2-492d-a767-f18c990af164",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/deliveryrules/:id?siteId=:siteId
Delete a delivery rule.
| Query Params | |
|---|---|
siteIdUUID |
The ID of the site for which to delete the delivery rule. This parameter is required. |
The following attributes are returned as part of the response.
| Attributes | |
|---|---|
taskId string |
The task id related to the delivery rule deletion. |
taskStatus string |
The status of the operation. |
Condition
| Required | |
|---|---|
triggerEnum |
Trigger for the condition. Possible values: COOKIE, HEADER, HTTP_METHOD, STATUS_CODE, and URL. |
operatorEnum |
Operator for the condition. Possible values: EQUALS, MATCHES, and MATCHES_REGULAR_EXPRESSION. |
targetString |
The target of the condition. |
httpMethodsArray[Enum] |
HTTP methods for the condition. Possible values are: GET, POST, PUT, DELETE, HEAD, PATCH, and OPTIONS. This fields is only used when trigger is set to HTTP_METHOD. |
Action
The action attributes needed to be passed will vary depending on the condition being specified.
| Possible Attributes | |
|---|---|
actionTypeEnum |
The type of action. Possible values: ADD_RESPONSE_HEADER, ADD_HEADER_TO_ORIGIN,ADD_HEADER_TO_CDN, NEVER_EXPIRE, DO_NOT_CACHE, CACHE, REDIRECT, HIDE_HEADER, MODIFY_HEADER, SIGN_URL, and BYPASS_CACHE. |
responseHeadersArray |
Headers for the actions expressed as a key-value pair. |
originHeadersArray |
Headers for the actions expressed as a key-value pair. |
cdnHeadersArray |
Headers for the actions expressed as a key-value pair. |
cacheTtlNumber |
Time to live of the cache. |
redirectUrlString |
The url to redirect to. |
headerPatternString |
The header to set the modifier in the response. |
passphraseString |
The passphrase for signing the url. |
passphraseFieldString |
The passphrase field for signing the url. |
md5TokenFieldString |
The MD5 token field for signing the url. |
ipAddressFilterString |
The ip address filter for signing the url. |
urlSignaturePathLengthString |
The url signature path length for signing the url. |
Images
StackPath Edge Computing makes use of images to deploy virtual machines within a workload. The image can be from StackPath default images or a custom one. Only non-deprecated images are returned by default.
Deploy and manage your images.
List images
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/images"
The above command returns a JSON structured like this:
{
"data": [
{
"stackId": "a8050b2b-39eb-4929-bce5-1af42055903e",
"id": "a8050b2b-39eb-4929-bce5-1af42055903e/centos7/v20201110",
"slug": "stackpath-edge",
"family": "centos7",
"tag": "v20201110",
"createdAt": "2020-11-10T20:33:32.609434Z",
"description": "Image using centos7",
"reference": "stackpath-edge/centos7:v20201110",
"status": "READY"
},
{
"stackId": "a8050b2b-39eb-4929-bce5-1af42055903e",
"id": "a8050b2b-39eb-4929-bce5-1af42055903e/ubuntu/v20201110",
"slug": "stackpath-edge",
"family": "ubuntu",
"tag": "v20201110",
"createdAt": "2020-11-10T20:34:11.328575Z",
"description": "Image using ubuntu",
"reference": "stackpath-edge/ubuntu:v20201110",
"status": "READY"
}
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/images
Retrieve a list of all images in a given environment.
| Optional | |
|---|---|
imageTypestring |
This query parameter can either be set to default to return the default StackPath images or custom to return the created custom images. Anything else will return all images. |
| Attributes | |
|---|---|
idstring |
An image's unique identifier. It is the combination of stackId/family/tag. |
stackIdstring |
The ID of the stack that an image belongs to. |
familystring |
The family of the image. |
tagstring |
The tag of the image. |
slugstring |
A workload's programmatic name. Workload slugs are used to build its instances names. |
statusstring |
The status of the workload. It can be either READY, PENDING, PROCESSING, FAILED or IMAGE_STATUS_UNKNOWN. |
createdAtstring |
Creation timestamp of the image. |
descriptionstring |
The description of the image. |
referencestring |
The reference of the image. |
Retrieve an image
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/images/a8050b2b-39eb-4929-bce5-1af42055903e/ubuntu/v20201110"
The above command returns a JSON structured like this:
{
"data": {
"stackId": "a8050b2b-39eb-4929-bce5-1af42055903e",
"id": "a8050b2b-39eb-4929-bce5-1af42055903e/ubuntu/v20201110",
"slug": "stackpath-edge",
"family": "ubuntu",
"tag": "v20201110",
"createdAt": "2020-11-10T20:34:11.328575Z",
"description": "test 2",
"reference": "stackpath-edge/ubuntu:v20201110",
"status": "READY"
}
}
GET /services/:service_code/:environment_name/images/:id
Retrieve an image in a given environment.
| Attributes | |
|---|---|
idstring |
An image's unique identifier. It is the combination of stackId/family/tag. |
stackIdstring |
The ID of the stack that an image belongs to. |
familystring |
The family of the image. |
tagstring |
The tag of the image. |
slugstring |
A workload's programmatic name. Workload slugs are used to build its instances names. |
statusstring |
The status of the workload. It can be either READY, PENDING, PROCESSING, FAILED or IMAGE_STATUS_UNKNOWN. |
createdAtstring |
Creation timestamp of the image. |
descriptionstring |
The description of the image. |
referencestring |
The reference of the image. |
Create a custom image
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/images"
Request body example for creating a custom image:
{
"family": "Ubuntu",
"tag": "v2021-01-01",
"workloadId": "c23652ed-0f15-47cf-a9b8-63e1e3aacb3c",
"instanceName": "w-john-ahd-wi-john-jsr-phx-0",
"description": "Ubuntu OS v4"
}
The above commands return a JSON structured like this:
{
"taskId": "1f64aefb-f980-400b-bc2d-5300376fa55e",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/images
| Required | |
|---|---|
familystring |
The family name of the custom image.Family must consist of lower case alphanumeric characters or '-' and must begin and end with an alphanumeric character. |
tagstring |
The tag of the image. A tag must be valid ASCII and may contain lowercase and uppercase letters, digits, underscores, periods and dashes. A tag must not start with a period or a dash and must contain a maximum of 128 characters. |
workloadIdstring |
The workloadId of the source workload the image will be created from. Only workloads of type VM are allowed |
instanceNamestring |
The name of one of the instance the create the image from. The name of the instance needs to be a valid instance of the workloadId provided. |
| Optional | |
|---|---|
descriptionstring |
The description of the custom image. |
Delete a custom image
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/images/1b932678-1038-4ab4-9fa4-c4c06e696e20"
The above command returns a JSON structured like this:
{
"taskId": "ef70cafa-0544-4709-a66a-c68595ee105a",
"taskStatus": "SUCCESS"
}
DELETE /services/:service_code/:environment_name/images/:id
Delete an image in a given environment.
| Attributes | |
|---|---|
taskId string |
The task id related to the image deletion. |
taskStatus string |
The status of the operation. |
DNS Zones
Create and manage your DNS zones.
List DNS Zones
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/dnszones"
The above command returns a JSON structured like this:
{
"data": [
{
"stackId": "87e22df5-cac9-4e42-9b75-02996af95566",
"accountId": "69b60c67-6175-4515-bb66-033108306X66",
"domain": "mydomain.com",
"version": "3",
"created": "2021-07-28T17:13:42.863239Z",
"updated": "2021-07-28T17:14:25.246331Z",
"nameservers": [
"xx2xx0.stackpathdns.net",
"ss3xx3.stackpathdns.net"
],
"disabled": false,
"id": "eb3ecdbe-d73b-40e6-a263-166accba75ed",
"verified": "2021-07-28T17:14:25.246331Z",
"status": "ACTIVE"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/dnszones
Retrieve a list of all DNS zones in a given environment.
| Attributes | |
|---|---|
idstring |
A zone's unique identifier. |
stackIdstring |
The ID of the stack that a site belongs to. |
accountIdstring |
The ID of the StackPath account that owns a zone. |
domainstring |
The name of the zone. |
versionstring |
The version of the zone. Version numbers are incremented automatically when a zone is updated. |
createdstring |
The date on which the DNS zone was created. |
updatedstring |
The date on which the DNS zone was last updated. |
nameserversArray[string] |
The hostnames of the StackPath resolvers that host a zone. Every zone has multiple name servers assigned by StackPath upon creation for redundancy purposes. |
disabledboolean |
Whether or not a zone has been disabled by the user. |
verifiedstring |
The date a zone's nameservers were last audited by StackPath. |
statusstring |
The status of the zone. It can either be ACTIVE, INACTIVE. |
Retrieve a DNS zone
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/dnszones/9ae3717a-006a-4aa7-b64b-8bc8d2f2d6e5"
The above command returns a JSON structured like this:
{
"data": {
"stackId": "87e22df5-cac9-4e42-9b75-02996af95566",
"accountId": "69b60c67-6175-4515-bb66-033108306X66",
"domain": "mydomain.com",
"version": "3",
"created": "2021-07-28T17:13:42.863239Z",
"updated": "2021-07-28T17:14:25.246331Z",
"nameservers": [
"xx2xx0.stackpathdns.net",
"ss3xx3.stackpathdns.net"
],
"disabled": false,
"id": "eb3ecdbe-d73b-40e6-a263-166accba75ed",
"verified": "2021-07-28T17:14:25.246331Z",
"status": "ACTIVE"
}
}
GET /services/:service_code/:environment_name/dnszones/:id
Retrieve a DNS zone in a given environment.
| Attributes | |
|---|---|
idstring |
A zone's unique identifier. |
stackIdstring |
The ID of the stack that a site belongs to. |
accountIdstring |
The ID of the StackPath account that owns a zone. |
domainstring |
The name of the zone. |
versionstring |
The version of the zone. Version numbers are incremented automatically when a zone is updated. |
createdstring |
The date on which the DNS zone was created. |
updatedstring |
The date on which the DNS zone was last updated. |
nameserversArray[string] |
The hostnames of the StackPath resolvers that host a zone. Every zone has multiple name servers assigned by StackPath upon creation for redundancy purposes. |
disabledboolean |
Whether or not a zone has been disabled by the user. |
verifiedstring |
The date a zone's nameservers were last audited by StackPath. |
statusstring |
The status of the zone. It can either be ACTIVE, INACTIVE. |
Create a DNS zone
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/dnszones"
Request body example for without DNS records to import:
{
"domain":"my-domain.com"
}
Request body example for with DNS records to import:
{
"domain": "my-domain.com",
"records": [
{
"name": "*",
"type": "NS",
"ttl": 3600,
"data": "ns1.above.com.",
"weight": 1
}
]
}
The above command returns a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/dnszones
Create a DNS zone in a given environment.
| Required | |
|---|---|
domainString |
The name of the zone. |
| Optional | |
|---|---|
recordsArray[Object] |
The list of DNS records to create. |
records.typeString |
A zone record's type. Zone record types describe the zone record's behavior. Supported values are A, AAAA, CAA, CNAME, MX, SRV, TXT or NS. Required for each record. |
records.nameString |
The name of the record. Use the value "@" to denote current root domain name. Required for each record. |
records.dataString |
A zone record's value. Required for each record. |
records.ttlinteger |
A zone record's time to live. A record's TTL is the number of seconds that the record should be cached by DNS resolvers. Use lower TTL values if you expect zone records to change often. Use higher TTL values for records that won't change to prevent extra DNS lookups by clients. Required for each record. |
records.weightinteger |
A zone record's priority. A resource record is replicated in StackPath's DNS infrastructure the number of times of the record's weight, giving it a more likely response to queries if a zone has records with the same name and type. |
Delete a DNS zone
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/dnszones/9ae3717a-006a-4aa7-b64b-8bc8d2f2d6e5"
The above command returns a JSON structured like this:
{
"taskId": "ef70cafa-0544-4709-a66a-c68595ee105a",
"taskStatus": "SUCCESS"
}
DELETE /services/:service_code/:environment_name/dnszones/:id
Delete a DNS zone
The following attributes are returned as part of the response.
| Attributes | |
|---|---|
taskId string |
The task id related to the DNS zone deletion. |
taskStatus string |
The status of the operation. |
Import DNS zone records
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/dnszones/9ae3717a-006a-4aa7-b64b-8bc8d2f2d6e5?operation=import"
Request body example:
{
"records": [
{
"name": "*",
"type": "NS",
"ttl": 3600,
"data": "ns1.above.com.",
"weight": 1
}
]
}
The above command returns a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/dnszones/:id?operation=import
Import DNS records into a DNS zone in a given environment.
| Optional | |
|---|---|
recordsArray[Object] |
The list of DNS records to import. |
records.typeString |
A zone record's type. Zone record types describe the zone record's behavior. Supported values are A, AAAA, CAA, CNAME, MX, SRV, TXT or NS. Required for each record. |
records.nameString |
The name of the record. Use the value "@" to denote current root domain name. Required for each record. |
records.dataString |
A zone record's value. Required for each record. |
records.ttlinteger |
A zone record's time to live. A record's TTL is the number of seconds that the record should be cached by DNS resolvers. Use lower TTL values if you expect zone records to change often. Use higher TTL values for records that won't change to prevent extra DNS lookups by clients. Required for each record. |
records.weightinteger |
A zone record's priority. A resource record is replicated in StackPath's DNS infrastructure the number of times of the record's weight, giving it a more likely response to queries if a zone has records with the same name and type. |
DNS Records
Create and manage your DNS records associated to your zones.
List DNS Records
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/dnsrecords?zoneId=337c7c26-31f4-4b2e-83dc-126exxxxxxWr"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "4eea2e59-8d06-4f37-8fd1-035e3314dxxD",
"stackId": "7fbea2c0-17d0-41df-b0b1-4d5c95234566",
"zoneId": "337c7c26-31f4-4b2e-83dc-126exxxxxxWr",
"name": "test1",
"type": "A",
"classCode": "IN",
"ttl": 21600,
"data": "127.0.0.0",
"weight": 1,
"created": "2021-07-28T17:14:07.928210Z",
"updated": "2021-07-28T17:14:07.928210Z"
},
{
"id": "0a18b323-72df-447a-af81-08a2ea62re45",
"stackId": "7fbea2c0-17d0-41df-b0b1-4d5c95234566",
"zoneId": "337c7c26-31f4-4b2e-83dc-126exxxxxxWr",
"name": "test2",
"type": "TXT",
"classCode": "IN",
"ttl": 300,
"data": "123 312 12",
"weight": 1,
"created": "2021-07-28T17:14:25.229376Z",
"updated": "2021-07-28T17:14:25.229376Z"
}
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/dnsrecords?zoneId=:zoneId
Retrieve a list of all DNS records in a given DNS zone in an environment.
| Query Params | |
|---|---|
zoneIdUUID |
The ID of the zone for which we list the records. This parameter is required. |
| Attributes | |
|---|---|
idstring |
A record's unique identifier. |
stackIdstring |
The ID of the stack that a record belongs to. |
zoneIdstring |
The ID of zone that the record belongs to. |
namestring |
The name of the record. Use the value "@" to denote current root domain name. |
typestring |
A zone record's type. Zone record types describe the zone record's behavior. |
classCodestring |
A zone record's class code. This is typically "IN" for Internet related resource records. |
ttl int |
A zone record's time to live. A record's TTL is the number of seconds that the record should be cached by DNS resolvers. Use lower TTL values if you expect zone records to change often. Use higher TTL values for records that won't change to prevent extra DNS lookups by clients. |
datastring |
A zone record's value. |
weight int |
A zone record's priority. A resource record is replicated in StackPath's DNS infrastructure the number of times of the record's weight, giving it a more likely response to queries if a zone has records with the same name and type. |
createdstring |
The date on which the DNS record was created. |
updatedstring |
The date on which the DNS record was last updated. |
Retrieve a DNS record
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/dnsrecords/0a18b323-72df-447a-af81-08a2ea62re45?zoneId=337c7c26-31f4-4b2e-83dc-126exxxxxxWr"
The above command returns a JSON structured like this:
{
"data": {
"id": "0a18b323-72df-447a-af81-08a2ea62re45",
"stackId": "7fbea2c0-17d0-41df-b0b1-4d5c95234566",
"zoneId": "337c7c26-31f4-4b2e-83dc-126exxxxxxWr",
"name": "test2",
"type": "TXT",
"classCode": "IN",
"ttl": 300,
"data": "123 312 12",
"weight": 1,
"created": "2021-07-28T17:14:25.229376Z",
"updated": "2021-07-28T17:14:25.229376Z"
}
}
GET /services/:service_code/:environment_name/dnsrecords/:id?zoneId=:zoneId
Retrieve a DNS record in a given DNS zone in an environment .
| Query Params | |
|---|---|
zoneIdUUID |
The ID of the zone for which we want to get the record. This parameter is required. |
| Attributes | |
|---|---|
idstring |
A record's unique identifier. |
stackIdstring |
The ID of the stack that a record belongs to. |
zoneIdstring |
The ID of zone that the record belongs to. |
namestring |
The name of the record. Use the value "@" to denote current root domain name. |
typestring |
A zone record's type. Zone record types describe the zone record's behavior. |
classCodestring |
A zone record's class code. This is typically "IN" for Internet related resource records. |
ttl int |
A zone record's time to live. A record's TTL is the number of seconds that the record should be cached by DNS resolvers. Use lower TTL values if you expect zone records to change often. Use higher TTL values for records that won't change to prevent extra DNS lookups by clients. |
datastring |
A zone record's value. |
weight int |
A zone record's priority. A resource record is replicated in StackPath's DNS infrastructure the number of times of the record's weight, giving it a more likely response to queries if a zone has records with the same name and type. |
createdstring |
The date on which the DNS record was created. |
updatedstring |
The date on which the DNS record was last updated. |
Create a DNS record
curl -X POST \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/dnsrecords?zoneId=337c7c26-31f4-4b2e-83dc-126exxxxxxWr"
Request body example for creating a DNS record:
{
"name": "*",
"type": "NS",
"ttl": 3600,
"data": "ns1.above.com.",
"weight": 1
}
The above command returns a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/dnsrecords?zoneId=:zoneId
Create a DNS record in a given environment.
| Query Params | |
|---|---|
zoneIdUUID |
The ID of the zone for which we want to create the record. This parameter is required. |
| Required | |
|---|---|
namestring |
The name of the record. Use the value "@" to denote current root domain name. |
typestring |
A DNS record's type. DNS record types describe the record's behavior. |
ttl int |
A DNS record's time to live. A record's TTL is the number of seconds that the record should be cached by DNS resolvers. Use lower TTL values if you expect zone records to change often. Use higher TTL values for records that won't change to prevent extra DNS lookups by clients. |
datastring |
A DNS record's value. |
| Optional | |
|---|---|
weight int |
A DNS record's priority. A resource record is replicated in StackPath's DNS infrastructure the number of times of the record's weight, giving it a more likely response to queries if a zone has records with the same name and type. |
Update a DNS record
curl -X PUT \
-H "MC-Api-Key: your_api_key" \
-d "request_body" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/dnsrecords/0a18b323-72df-447a-af81-08a2ea62re45?zoneId=337c7c26-31f4-4b2e-83dc-126exxxxxxWr"
Request body example for creating a DNS record:
{
"name": "*",
"type": "NS",
"ttl": 3600,
"data": "ns1.above.com.",
"weight": 1
}
The above command returns a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/dnsrecords/:id?zoneId=:zoneId
Update a DNS record in a given environment.
| Query Params | |
|---|---|
zoneIdUUID |
The ID of the zone for which we want to update the record. This parameter is required. |
| Required | |
|---|---|
namestring |
The name of the record. Use the value "@" to denote current root domain name. |
typestring |
A DNS record's type. DNS record types describe the record's behavior. |
ttl int |
A DNS record's time to live. A record's TTL is the number of seconds that the record should be cached by DNS resolvers. Use lower TTL values if you expect zone records to change often. Use higher TTL values for records that won't change to prevent extra DNS lookups by clients. |
datastring |
A DNS record's value. |
| Optional | |
|---|---|
weight int |
A DNS record's priority. A resource record is replicated in StackPath's DNS infrastructure the number of times of the record's weight, giving it a more likely response to queries if a zone has records with the same name and type. |
Delete a DNS record
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/stackpath/test-area/dnsrecords/0a18b323-72df-447a-af81-08a2ea62re45?zoneId=337c7c26-31f4-4b2e-83dc-126exxxxxxWr"
The above command returns a JSON structured like this:
{
"taskId": "ef70cafa-0544-4709-a66a-c68595ee105a",
"taskStatus": "SUCCESS"
}
DELETE /services/:service_code/:environment_name/dnsrecords/:id?zoneId=:zoneId
Delete a DNS record.
| Query Params | |
|---|---|
zoneIdUUID |
The ID of the zone for which we want to delete the record. This parameter is required. |
| Attributes | |
|---|---|
taskId string |
The task id related to the DNS zone deletion. |
taskStatus string |
The status of the operation. |
Amazon Web Services plugin
The Amazon Web Services (AWS) plugin provides endpoints for carrying out operations on CloudMC compute and networking entities. It also enforces CloudMC's environment-centric multi-tenancy model and RBAC over top of AWS.
Compute
Instances
Deploy and manage your instances.
List instances
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-env/instances"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "i-03dffc71c7d649bb1",
"name": "NameOfMyInstance",
"rootDeviceName": "/dev/xvda",
"imageId": "ami-0947d2ba12ee1ff75",
"instanceType": "t2.micro",
"launchTime": "2022-01-11T20:57:30Z",
"availabilityZone": "us-east-1a",
"privateDnsName": "ip-172-31-90-212.ec2.internal",
"privateIpAddress": "172.31.90.212",
"publicDnsName": "ec2-54-210-168-154.compute-1.amazonaws.com",
"publicIpAddress": "54.210.168.154",
"state": "running",
"subnetId": "subnet-0ac78483b1159f7e9",
"vpcId": "vpc-040e8c412dc149b2a",
"architecture": "x86_64",
"clientToken": "7fe789d0-1e84-4c6a-886a-828b99f8525b",
"rootDeviceType": "ebs",
"virtualizationType": "hvm",
"tags": [
{
"name": "NameOfMyInstance",
"tag2": "wowASecondValueIdkNotRequired"
}
],
"coreCount": 1,
"threadsPerCore": 1,
"securityGroupName": "default",
"minCount": 0,
"maxCount": 0,
"region": "us-east-1",
"attachments": [
{
"attachTime": "2022-01-11T20:57:31Z",
"device": "/dev/xvda",
"instanceId": "i-03dffc71c7d649bb1",
"state": "attached",
"volumeId": "vol-0c8dd88e0743c368b",
"deleteOnTermination": true
}
]
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/instances
Retrieve a list of all instances in a given environment.
| Attributes | |
|---|---|
idstring |
The ID of the instance. |
namestring |
The name of the instance. |
rootDeviceNamestring |
The device name of the root device volume (for example, /dev/sda1 ). |
imageIdstring |
The ID of the AMI used to launch the instance. |
instanceTypestring |
The instance type. |
launchTimestring |
The time the instance was launched. |
availabilityZonestring |
The Availability Zone of the instance. |
privateDnsNamestring |
(IPv4 only) The private DNS hostname name assigned to the instance. This DNS hostname can only be used inside the Amazon EC2 network. This name is not available until the instance enters the running state. |
privateIpAddressstring |
The private IPv4 address assigned to the instance. |
publicDnsNamestring |
(IPv4 only) The public DNS name assigned to the instance. This name is not available until the instance enters the running state. For EC2-VPC, this name is only available if you've enabled DNS hostnames for your VPC. |
publicIpAddressstring |
The public IPv4 address, or the Carrier IP address assigned to the instance, if applicable. |
statestring |
The current state of the instance. |
subnetIdstring |
[EC2-VPC] The ID of the subnet in which the instance is running. |
vpcIdstring |
[EC2-VPC] The ID of the VPC in which the instance is running. |
architecturestring |
The architecture of the image. |
clientTokenstring |
The idempotency token you provided when you launched the instance, if applicable. |
rootDeviceTypestring |
The root device type used by the AMI. The AMI can use an EBS volume or an instance store volume. |
virtualizationTypestring |
The virtualization type of the instance. |
tagsArray[object] |
Any tags assigned to the instance. Tags are key value pairs. |
coreCountint |
The number of CPU cores for the instance. |
threadsPerCore>int |
The number of threads per CPU core. |
securityGroupNamestring |
The name of the security group. |
maxCountinteger |
The maximum number of instances to create. Cannot be greater than 20. |
minCountinteger |
The minimum number of instances to create. Should be greater than 1. |
regionstring |
The region where the instance will be deployed. |
attachmentsArray[object] |
The list of volumes to which the instance is attached. |
Retrieve an instance
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-area/instances/i-03dffc71c7d649bb1"
The above command returns a JSON structured like this:
{
"data": {
"id": "i-03dffc71c7d649bb1",
"name": "NameOfMyInstance",
"rootDeviceName": "/dev/xvda",
"imageId": "ami-0947d2ba12ee1ff75",
"instanceType": "t2.micro",
"launchTime": "2022-01-11T20:57:30Z",
"availabilityZone": "us-east-1a",
"privateDnsName": "ip-172-31-90-212.ec2.internal",
"privateIpAddress": "172.31.90.212",
"publicDnsName": "ec2-54-210-168-154.compute-1.amazonaws.com",
"publicIpAddress": "54.210.168.154",
"state": "running",
"subnetId": "subnet-0ac78483b1159f7e9",
"vpcId": "vpc-040e8c412dc149b2a",
"architecture": "x86_64",
"clientToken": "7fe789d0-1e84-4c6a-886a-828b99f8525b",
"rootDeviceType": "ebs",
"virtualizationType": "hvm",
"tags": [
{
"name": "NameOfMyInstance",
"tag2": "wowASecondValueIdkNotRequired"
}
],
"coreCount": 1,
"threadsPerCore": 1,
"securityGroupName": "default",
"minCount": 0,
"maxCount": 0,
"region": "us-east-1",
"attachments": [
{
"attachTime": "2022-01-11T20:57:31Z",
"device": "/dev/xvda",
"instanceId": "i-03dffc71c7d649bb1",
"state": "attached",
"volumeId": "vol-0c8dd88e0743c368b",
"deleteOnTermination": true
}
]
}
}
GET /services/:service_code/:environment_name/instances/:id
Retrieve an instance in a given environment.
| Attributes | |
|---|---|
idstring |
The ID of the instance. |
namestring |
The name of the instance. |
rootDeviceNamestring |
The device name of the root device volume (for example, /dev/sda1 ). |
imageIdstring |
The ID of the AMI used to launch the instance. |
instanceTypestring |
The instance type. |
launchTimestring |
The time the instance was launched. |
availabilityZonestring |
The Availability Zone of the instance. |
privateDnsNamestring |
(IPv4 only) The private DNS hostname name assigned to the instance. This DNS hostname can only be used inside the Amazon EC2 network. This name is not available until the instance enters the running state. |
privateIpAddressstring |
The private IPv4 address assigned to the instance. |
publicDnsNamestring |
(IPv4 only) The public DNS name assigned to the instance. This name is not available until the instance enters the running state. For EC2-VPC, this name is only available if you've enabled DNS hostnames for your VPC. |
publicIpAddressstring |
The public IPv4 address, or the Carrier IP address assigned to the instance, if applicable. |
statestring |
The current state of the instance. |
subnetIdstring |
[EC2-VPC] The ID of the subnet in which the instance is running. |
vpcIdstring |
[EC2-VPC] The ID of the VPC in which the instance is running. |
architecturestring |
The architecture of the image. |
clientTokenstring |
The idempotency token you provided when you launched the instance, if applicable. |
rootDeviceTypestring |
The root device type used by the AMI. The AMI can use an EBS volume or an instance store volume. |
virtualizationTypestring |
The virtualization type of the instance. |
tagsArray[object] |
Any tags assigned to the instance. Tags are key value pairs. |
coreCountint |
The number of CPU cores for the instance. |
threadsPerCore>int |
The number of threads per CPU core. |
securityGroupNamestring |
The name of the security group. |
maxCountinteger |
The maximum number of instances to create. Cannot be greater than 20. |
minCountinteger |
The minimum number of instances to create. Should be greater than 1. |
regionstring |
The region where the instance will be deployed. |
attachmentsArray[object] |
The list of volumes to which the instance is attached. |
Create an instance
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-area/instances"
Request body example for an instance with custom security group:
{
"name": "name-of-the-instance",
"imageId": "ami-08e4e35cccc6189f4",
"instanceType": "t2.micro",
"securityGroupScope": "CUSTOM",
"securityGroupName": "sc-custom-user-iklp",
"securityGroupDescription": "Custom: allow only port 8085",
"minCount": 1,
"maxCount": 1,
"region": "us-east-1",
"sshKey": {
"keyName": "user ssh key"
},
"ipPolicies": [{
"ipRange": "0.0.0.0/0",
"protocol": "TCP",
"portRange": "5200-5220"
}],
"blockDeviceMappings": [{
"type": "Root",
"attachmentDeviceName": "/dev/xvda",
"deleteOnTermination": true,
"size": 30,
"volumeType": "gp3",
"iops": 3000,
"throughput": 250
}],
"vpcId": "vpc-0b23fed563eebe635",
"subnetId": "subnet-0d4d9d813e763d403",
"volumesToAttach": [{
"volumeId": "vol-1",
"device": "/dev/sdg",
}]
}
The above commands return a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/tasks/7135ae25-8488-4bc5-a289-285c84a00a84"
The above command(s) return(s) JSON structured like this:
{
"data": {
"id": "7135ae25-8488-4bc5-a289-285c84a00a84",
"status": "SUCCESS",
"created": "2021-04-20T20:58:59.952881-04:00",
"result": {
"name": "i-pspensieri-virhq",
"imageId": "ami-04505e74c0741db8d",
"sshKey": {
"keyName": "ssh-pspensieri-wjigo",
"privateKey": "-----BEGIN RSA PRIVATE KEY-----\nMEIEowIBAAKCAQEA3h9R/BwcvfdA9CyZcJ9F/MZpeRlTdLGr2YULl9IWMXehpjae\nhckwYIYSfsaiGJE6Y9ChZFpfn1pKjZXH1/9YYcSFMh/hrh341oD/WRH851hMagbi\nK5Bo69XcPYLi34eCs4owFXQcpvMMiuhzxQXbfbVDPSdEHA+6Td9JbX/yPdm9m0Ag\n6yMYJBK3qGjFNzUFKGI51K/zKpxf4eQIpVaG9Lt4WtFQK3Biy0eR38MmcBmp3QVN\n3WOq5gk7NlcCsdHn4UV/UuI0DGsQcLaQ/ZyM+75lXpVe18pPy3aZNGcnuSQ2oqpg\nEsbCcv7L+YCPGiF1eJkQu0K2fEOm23qHf7CuSQIDAQABAoIBAH9T9OtQMimzUsil\nyE+G/deo5U1F91EtiBVo7vxYseApc8CUDssiSVkLgg6qTsFGfvI45ktggvAWEiaX\ndbeb6E4jGTdijzwAcmSEDdxBM3hqZWNiDsRqQ7rtHRMltGfuhj3lOSsTJFmPeeEm\n3zZR5UBqZ+DmYWS0n1eEZ9MdRP+ugFR+VMYYoxoD5h6NemOEXUnFGq8Drtzj/JAG\ncEqAJPbOJeSmWfgPaUjmfWrFrctL3H4oS802OBpDObmk2tG738w9o4ttC1oSXdW+\nw5tqAKNJxPyxS+jDtA1eiB5KbPiLDeg/6aDIdyKzICCzsRzOQEtTNp9J7UBoy9LA\nosuv2wECgYEA8nQEMd5vW0NK/KV17+lWQ8+B9qyEewr3Z9MxU4PDF+K+jlh7obUn\nK/C/JZqr0xhex3nZgg+WXFPPnOMWCxLI2o3MuDsfaLs7se99iCt6cgtf6i3keM2e\nsoUl1tDYqWFvqPvqQPGkWcS4l2rxh8RrfcKLdigZGPAWMff/8CaxNjsCgYEA6oh/\nQCMSGB4Bu6Yj8cEDYi13WJuImCyZdN5Ezd/UF3j/xXchW2SPM6KaQrikBgjWFqcs\nKhORFjMvA/YnGNSF4Tkar+q6WlCL4YCXf7O6/aDs0Q+cx1WDE8gmvuvvPApi9KlF\n4yikpQG4cslMnh5UFFIMt+L30BEK64rcydplsUsCgYA4BXSerT3fwYnHHNhGag0D\nuCPYgn5OC/ekptjj6jMfBsZvD6TpdXkqnwMbxkRjj2L/Bnmqor1kcf0rzBDg2CNO\n1Krz+r1ELtcZQzQnTZyKU3SDIL2E6EX+C+P1YeZeJORvEF5NSUhncZwRaKWMcGdB\n9LzSvWsnJvqJ6zrZG6eg1wKBgA+mPf90l59+WRVBV8Ko42XorL7/2dR1nWO79RFb\nrxZF36M4eMRVaGzEm9B564/vhQGL9Bl2psa5cZitExzICYrmuY4ldnvSRhMs9m7x\n+jc0RrkIdqiiXxWx1EwHCDaURK4YoW4v5xSPkdQu9GrUkT2t3+VhQrHigT0ITgU2\nCnUTAoGBAJVtiAdLq7zJrsb+QjGCJnNMrV9lG3WmR15/TFkoNPygG17XcymaWCDc\n/nN7J9gjH/GozL8a1OtqNHWczydfKU7DNMhCoyml0RS0454FMPNkT4R6P7UfOk2o\nGjr5AV04BLNdutLlEc2ny+ce8R1/S/uGdP0p31OoFUEHRjLFqlkG\n-----END RSA PRIVATE KEY-----"
},
"blockDeviceMappings": [
{
"volumeType": "gp2",
"encrypted": false,
"size": 8,
"fastRestored": false,
"attachmentDeviceName": "/dev/sda1",
"deleteOnTermination": true,
"type": "Root",
"multiAttachEnabled": false,
"rootDeviceImageId": "ami-04505e74c0741db8d"
}
],
"instanceType": "c1.medium",
"threadsPerCore": 0,
"coreCount": 0,
"maxCount": 1,
"tags": {},
"securityGroupId": "sg-056a936ec78d4a651",
"vpcId": "vpc-084ca52571cec5c12",
"releaseElasticIp": true,
"minCount": 1,
"region": "us-east-1",
"securityGroupScope": "ALL"
}
}
}
POST /services/:service_code/:environment_name/instances
Create a new instance in a given environment.
| Required | |
|---|---|
namestring |
The name of the instance. |
regionstring |
The region where the instance will be deployed. |
imageId string |
The imageId to be used deployed with the instance. Represents the unique identifier of an amazon machine image (AMI). The imageId needs to be compatible with the machine type. The imageId needs to be available in the given region of the instance. |
instanceTypestring |
The type of the instance. Represents the specification of the instance (cpu, memory, storage). The instance type needs to be available in the given region of the instance. |
securityGroupScopeenum |
Possible values are CUSTOM, DEFAULT and ALL. Represents the scope of the security group. CUSTOM scope implies that an IP policy will be provided with the payload indicating the custom ports and IP range to use. It indicates that only traffic matching the IP policy will be able to reach the instance. ALL scope allows all traffic from all sources. It is the default scope for an instance. No need to provide an IP policy if that is the selected scope. Default allows HTTP, HTTPS and SSH traffic by opening ports 80, 443 and 22 to all public IPs. No need to provide an IP policy if that is the selected scope. |
securityGroupNamestring |
The name of the security group. |
securityGroupDescriptionstring |
The description of the security group. |
maxCountinteger |
The maximum number of instances to create. Cannot be greater than 20. |
minCountinteger |
The minimum number of instances to create. Should be greater than 1. |
sshKey.keyNamestring |
The name of the SSH key to be used to connect to this instance via SSH. |
blockDeviceMappingsArray |
Volumes to attached to the instance on launch. To be left empty if the default root volume should be used. |
volumesToAttachArray |
Volumes to attached to the instance after it is launched. Only volumes in the same availability zone as the subnet can be attached. |
| Optional | |
|---|---|
ipPoliciesArray |
The IP policy to use for the security group if the security group scope is CUSTOM. |
ipPolicies.ipRangestring |
The IP range in CIDR block notation of an IPV4 compatible string. Indicates the allowed IP(s) to reach the instance. |
ipPolicies.protocolenum |
Possible values are UDP, TCP and ICMP. Indicates the allowed protocol to use to reach the instance. |
ipPolicies.portRangeinteger |
The allowed IP range. Can be a single port or a port range, such as 1024-65535 |
blockDeviceMappings.typestring |
Indicates whether the volume is "Root" or "EBS", used to calculate minimum sizing. |
blockDeviceMappings.attachmentDeviceNamestring |
The device name for the attached volume. |
blockDeviceMappings.deleteOnTerminationboolean |
Whether or not the volume should be deleted alongside the instance. |
blockDeviceMappings.sizeinteger |
The required size of the attached volume. |
blockDeviceMappings.volumeTypestring |
The Amazon EBS volume type (gp2, gp3, io1, io2, st1, sc1, standard). Refer to "Create Volume" docs to see volume types & limits for their respective fields. |
blockDeviceMappings.iopsinteger |
Describes the maximum number of input/output operations per second (IOPS) supported by the volume type. This field is only valid for volume types gp3, io1, and io2. |
blockDeviceMappings.throughputinteger |
The throughput performance in MiB/s supported by the volume type. This field is only valid for gp3 volumes. |
vpcId string |
The id of the VPC in which the instance will be deployed. This must be specified if there is no default VPC in the selected region or if you decide to provide a subnet. |
subnetId string |
The id of the subnet in which the instance will be deployed. If this is not specified, the instance will be deployed in one of the default subnets in the default VPC. The subnet specified must belong to the VPC specified. |
| Attributes | |
|---|---|
idstring |
The task's ID. |
statusstring |
The task's status. |
createdDate |
The task's creation date. |
resultObject |
The task result, containing details of the created instance. |
result.namestring |
The name of the instance. |
result.regionstring |
The region where the instance was deployed. |
result.imageIdstring |
The ID of the AMI used to launch the instance. |
result.sshKeyObject |
The SSH key details. |
result.sshKey.keyNamestring |
The name of the SSH key to be used to connect to this instance. |
result.sshKey.privateKeystring |
The private SSH key to be used to connect to this instance. |
result.blockDeviceMappingsObject |
Volumes attached to the instance on launch. |
result.instanceTypestring |
The instance type. |
result.threadsPerCoreint |
The number of threads per CPU core. |
result.coreCountint |
The number of CPU cores for the instance. |
result.minCountint |
The minimum number of instances to create. |
result.maxCountint |
The maximum number of instances to create. |
result.tagsArray[object] |
Any tags assigned to the instance. Tags are key value pairs. |
result.securityGroupIdstring |
The ID of the security group. |
result.vpcIdstring |
[EC2-VPC] The ID of the VPC in which the instance is running. |
result.securityGroupScopestring |
Represents the scope of the security group. Possible values are CUSTOM, DEFAULT and ALL. |
Delete an instance
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-area/instances/i-0d1f9106cd0e0dff7"
The above command returns a JSON structured like this:
{
"taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/instances/:id
Delete an Instance in a given environment.
| Attributes | |
|---|---|
taskId string |
The task id related to the instance deletion. |
taskStatus string |
The status of the operation. |
If the Instance belongs to a kubernetes cluster, a new instance will automatically be created in the place of this one unless the cluster that it belongs to is deleted.
Start an instance
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-area/instances/i-0d1f9106cd0e0dff7?operation=start"
The above command returns a JSON structured like this:
{
"taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
"taskStatus": "PENDING"
}
START /services/:service_code/:environment_name/instances/:id
| Attributes | |
|---|---|
taskId string |
The task id related to the instance to be started. |
taskStatus string |
The status of the operation. |
Stop an instance
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-area/instances/i-0d1f9106cd0e0dff7?operation=stop"
The above command returns a JSON structured like this:
{
"taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
"taskStatus": "PENDING"
}
STOP /services/:service_code/:environment_name/instances/:id
| Attributes | |
|---|---|
taskId string |
The task id related to the instance to be stopped. |
taskStatus string |
The status of the operation. |
Associate an Elastic IP to an Instance
You can enable communication with the Internet by associating an Elastic IP to an Instance. In other words, an Elastic IP acts as the bridge between a Virtual Private Cloud (VPC) and an Instance.
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws-tesv/test/instances/i-00b2dcf0e059a2f1e?operation=associate"
Request body to associate an Elastic IP to an Instance:
{
"vpcId": "vpc-08a3263852fd4fb2a",
"elasticIp": {
"id": "eipalloc-0b1822bb64a812884"
}
}
The above command returns a JSON structured like this:
{
"taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/instances/:id?operation=associate
| Required | |
|---|---|
vpcIdstring |
The ID of the VPC to associate this instance to. |
elasticIp.idstring |
The ID of the Elastic IP to associate this instance to. |
Disassociate an Elastic IP from an instance
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-area/instances/i-0d1f9106cd0e0dff7?operation=disassociate"
The above command returns a JSON structured like this:
{
"taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/instances/:id?operation=disassociate
| Attributes | |
|---|---|
taskId string |
The task id related to the instance to be disassociated. |
taskStatus string |
The status of the operation. |
Storage
Volumes
Create an Amazon EBS volume to attach to any EC2 instance in the same Availability Zone.
List Volumes
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-env/volumes"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "vol-02929c8a1bcbf5f5f",
"name": "api-volume",
"attachments": [
{
"attachTime": "2022-01-11T20:57:31Z",
"device": "/dev/xvda",
"instanceId": "i-03dffc71c7d649bb1",
"state": "attached",
"volumeId": "vol-02929c8a1bcbf5f5f",
"deleteOnTermination": true
}
],
"availabilityZone": "us-east-1a",
"createTime": "2020-11-19T03:41:51Z",
"encrypted": false,
"size": 1,
"snapshotId": "",
"state": "available",
"iops": 100,
"tags": [],
"volumeType": "gp2",
"fastRestored": false,
"multiAttachEnabled": false
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/volumes
Retrieve a list of all volumes in a given environment.
| Attributes | |
|---|---|
idstring |
The ID of the volume. |
namestring |
The volume name of the root device volume (for example, /dev/sda1). |
attachments Array[object] |
The list of instances to which the volume is attached. |
availabilityZone string |
The Availability Zone of the volume. |
createTime string |
The timestamp when the volume was created. |
encrypted boolean |
Indicates whether the volume is encrypted. |
size int |
The size of the volume in GiB. |
snapshotId string |
The snapshot from which the volume was created. |
state string |
The state of the volume (creating, available, in-use, deleting, deleted, error). |
iops int |
Describes the maximum number of input/output operations per second (IOPS) that the volume should provide. |
tags Array[object] |
Any tags assigned to the volume. Tags are key value pairs. |
volumeType string |
The Amazon EBS volume type (gp2, gp3, io1, io2, st1, sc1, standard). |
fastRestored boolean |
Indicates whether the volume was created from a snapshot that is enabled for fast snapshot restore. |
multiAttachEnabled boolean |
Indicates whether the volume is enabled for Multi-Attach. |
Retrieve a volume
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-area/volumes/vol-0c8dd88e0743c368b"
The above command returns a JSON structured like this:
{
"data": {
"id": "vol-0c8dd88e0743c368b",
"name": "vol-0c8dd88e0743c368b",
"attachments": [
{
"attachTime": "2022-01-11T20:57:31Z",
"device": "/dev/xvda",
"instanceId": "i-03dffc71c7d649bb1",
"state": "attached",
"volumeId": "vol-0c8dd88e0743c368b",
"deleteOnTermination": true
}
],
"availabilityZone": "us-east-1a",
"createTime": "2022-01-11T20:57:31.675Z",
"encrypted": false,
"size": 8,
"snapshotId": "snap-0299d083f0ce6cd12",
"state": "in-use",
"iops": 100,
"tags": [],
"volumeType": "gp2",
"fastRestored": false,
"multiAttachEnabled": false
}
}
GET /services/:service_code/:environment_name/volumes/:id
Retrieve a volume in a given environment.
| Attributes | |
|---|---|
idstring |
The ID of the volume. |
namestring |
The volume name of the root device volume (for example, /dev/sda1). |
attachments Array[object] |
The list of instances to which the volume is attached. |
availabilityZone string |
The Availability Zone of the volume. |
createTime string |
The timestamp when the volume was created. |
encrypted boolean |
Indicates whether the volume is encrypted. |
size int |
The size of the volume in GiB. |
snapshotId string |
The snapshot from which the volume was created. |
state string |
The state of the volume (creating, available, in-use, deleting, deleted, error). |
iops int |
Describes the maximum number of input/output operations per second (IOPS) that the volume should provide. |
tags Array[object] |
Any tags assigned to the volume. Tags are key value pairs. |
volumeType string |
The Amazon EBS volume type (gp2, gp3, io1, io2, st1, sc1, standard). |
fastRestored boolean |
Indicates whether the volume was created from a snapshot that is enabled for fast snapshot restore. |
multiAttachEnabled boolean |
Indicates whether the volume is enabled for Multi-Attach. |
Create Volume
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-env/volumes"
Request body example for a volume:
json { "name": "api-volume", "availabilityZone": "us-east-1a", "size": 1, "iops": 100, "throughput": 125, "volumeType": "gp3", "multiAttachEnabled": false }The above command returns a JSON structured like this:
{
"taskId": "35d38672-8772-4b04-b1ca-1b13b97638ca",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/volumes
Retrieve a list of all volumes in a given environment.
| Attributes | |
|---|---|
availabilityZone string |
The Availability Zone of the volume within the service connection's default region policy. |
size int |
The size of the volume in GiB. Size is a required field for all volume types. |
volumeType string |
The Amazon EBS volume type. Below is a list of the possible volume types and the limits for their respective fields. |
- gp2 (1-16,384 GiB Size)
- gp3 (1-16,384 GiB Size, 3,000-16,000 IOPS, 125-1000 MiB/s Throughput)
- io1 (4-16,384 GiB Size, 100-64,000 IOPS, 50:1 IOPS/GiB ratio)
- io2 (4-16,384 GiB Size, 100-256,000 IOPS, 1000:1 IOPS/GiB ratio)
- sc1 (125-16,384 GiB Size)
- sc2 (125-16,384 GiB Size)
- standard (1-1,024 GiB Size)
| Optional | |
|---|---|
namestring |
The volume name. A default name will be created if there isn't one provided. |
iops int |
Describes the maximum number of input/output operations per second (IOPS) that the volume should provide. This field is only valid for gp3, io1, and io2 volume types. It is mandatory for io1 and io2 volumes. |
throughput int |
The throughput performance in MiB/s that the volume can support. This field is required for gp3 volumes. |
multiAttachEnabled boolean |
Indicates whether the volume is enabled for Multi-Attach. This is only supported for io1 and io2 volume types. |
Modify Volume
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-area/volumes/vol-0c8dd88e0743c368b"
Request body example for a volume:
json { "name": "api-volume", "id": "vol-0c8dd88e0743c368b", "size": 1, "iops": 100, "throughput": 125, "volumeType": "gp3", "multiAttachEnabled": false, "attachments": [ { "attachTime": "2022-01-11T20:57:31Z", "device": "/dev/xvda", "instanceId": "i-03dffc71c7d649bb1", "state": "attached", "volumeId": "vol-0c8dd88e0743c368b", "deleteOnTermination": true } ] }The above command returns a JSON structured like this:
{
"taskId": "35d38672-8772-4b04-b1ca-1b13b97638ca",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/volumes/:id
Modify a volume in a given environment environment.
| Attributes | |
|---|---|
idstring |
The ID of the volume. |
namestring |
The volume name of the root device volume (for example, /dev/sda1). |
attachments Array[object] |
The list of instances to which the volume is attached. |
size int |
The size of the volume in GiB. |
iops int |
Describes the maximum number of input/output operations per second (IOPS) that the volume should provide. |
volumeType string |
The Amazon EBS volume type (gp2, gp3, io1, io2, st1, sc1, standard). |
multiAttachEnabled boolean |
Indicates whether the volume is enabled for Multi-Attach. |
Delete a volume
Note: only volumes in an "available" state can be deleted
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-area/volumes/vol-0d1f9106cd0e0dff7"
The above command returns a JSON structured like this:
{
"taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/volumes/:id
| Attributes | |
|---|---|
taskId string |
The task id related to the instance deletion. |
taskStatus string |
The status of the operation. |
Attach a volume
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-area/volumes/vol-0d1f9106cd0e0dff7?operation=attach"
Request body example for a volume:
json { "instanceIdToAttach": "i-0b4e945ee65072b8a", "attachmentDeviceName": "/dev/sda1" }| Attributes | | |----------------------------|-------------------------------------------------| |instanceIdToAttach
string | Id of the instance the volume will be attached to (must be in the same availability zone). | |attachmentDeviceName
string | The device name that you assign is used by Amazon EC2. The device names that you're allowed to assign depends on the virtualization type of the selected instance. | - Linux device names: /dev/sdf through /dev/sdp - Windows device names: /dev/xvdf through /dev/xvdz - Linux root device names: /dev/sda1 or /dev/xvda (depending on the AMI) - Windows root device names: /dev/sda1The above command returns a JSON structured like this:
json { "taskId": "c8f44de4-e36f-456d-9802-3fb59cce3de2", "taskStatus": "PENDING" }
POST /services/:service_code/:environment_name/volumes/:id
| Attributes | |
|---|---|
taskId string |
The task id related to the instance attachment. |
taskStatus string |
The status of the operation. |
Detach a volume
Note: Only attached volumes can be detached. Detaching a root device volume will result in stopping the instance before detaching the volume.
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-area/volumes/vol-0d1f9106cd0e0dff7?operation=detach"
Request body example for a volume:
json { "instanceIdToDetach": "i-0e0d3jh110d1f9106" }The above command returns a JSON structured like this:
json { "taskId": "30121175-926a-4fd2-991b-ff303ffdf905", "taskStatus": "PENDING" }
POST /services/:service_code/:environment_name/volumes/:id
| Attributes | |
|---|---|
taskId string |
The task id related to the instance detachment. |
taskStatus string |
The status of the operation. |
S3
API Credentials
View and manage your s3 object-storage API credentials. You need to be a member of the environment to operation on these resources.
List credentials
curl --request GET \
--url 'https://cloudmc_endpoint/v1/services/aws/test-env/apiCredentials/global' \
--header 'Mc-Api-key: your_api_key'
The above command returns JSON structured like this:
{
"data": [
{
"accessKeyId": "AKIASQ3YW7O2RARDARUO",
"region": "global"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/apiCredentials
Retrieves a list of aws s3 API credentials. There will only ever be one entry in this list if a user has credentials.
| Attributes | |
|---|---|
accessKeyIdstring |
The ID for your s3 access key. |
regionstring |
The region the access key belongs to. Will always be 'global' for AWS. |
Get credentials
curl --request GET \
--url 'https://cloudmc_endpoint/v1/services/aws/test-env/apiCredentials/global' \
--header 'Mc-Api-key: your_api_key'
The above command returns a JSON structured like this:
{
"data": {
"accessKeyId": "AKIASQ3YW7O2RARDARUO",
"region": "global"
}
}
GET /services/:service_code/:environment_name/apiCredentials/global
Retrieves an access key by region. The only region supported for AWS is 'global'.
| Attributes | |
|---|---|
accessKeyIdstring |
The ID for your s3 access key. |
regionstring |
The region the access key belongs to. Will always be 'global' for AWS. |
Generate credentials
curl --request POST \
--url 'https://cloudmc_endpoint/api/v2/services/aws/test-env/apiCredentials?operation=generate' \
--header 'Mc-Api-key: your_api_key'
The above command returns JSON structured like this:
{
"data": {
"accessKeyId": "AKIASQ3YW7O2YA4SUQEC",
"secretKey": "YOUR_SECRET_KEY",
"region": "global"
},
"taskId": "fa565b90-e530-4abe-b88a-8aa6adc4dfc6",
"taskStatus": "SUCCESS"
}
POST /services/:service_code/:environment_name/apiCredentials?operation=generate
Generates, or regenerates if credentials are existing, access key credentials on the AWS environment. Regenerating will permanently delete the previous credentials saved for your user.
The secret key should be saved immediately after generation as it will be not be retrievable afterwards.
Return value:
| Attributes | |
|---|---|
accessKeyIdstring |
The ID for your s3 access key. |
secretKeystring |
The secret key for your s3 access key. Should be saved. |
regionstring |
The region the access key belongs to. Will always be 'global' for AWS. |
taskId string |
The task ID. |
taskStatus string |
The status of the operation. |
Delete credentials
curl --request DELETE \
--url `https://cloudmc_endpoint/api/v2/services/aws-aaaa/emcilroy-local/apiCredentials/global` \
--header 'Mc-Api-Key: your_api_key'
The above command returns JSON structured like this:
{
"taskId": "0773c033-8f0c-4366-bfe3-ca544b7cb3ac",
"taskStatus": "SUCCESS"
}
DELETE /services/:service_code/:environment_name/apiCredentials/global
Deletes the access credentials for your aws environment.
Return value:
| Attributes | |
|---|---|
taskId string |
The task ID. |
taskStatus string |
The status of the operation. |
Buckets
View and manage your buckets.
List Buckets
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/aws/test-env/buckets"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "us-east-1/bucketOne",
"name": "bucketOne",
"region": "us-east-1",
"created": "Tue Mar 01 16:13:29 EST 2022",
"url": "https://bucketOne.s3.amazonaws.com/"
},
{
"id": "ap-south-1/bucketTwo",
"name": "bucketTwo",
"region": "ap-south-1",
"created": "Fri Mar 04 16:20:29 EST 2022",
"url": "https://bucketTwo.s3.amazonaws.com/"
}
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/buckets
Retrieve a list of all buckets from Amazon S3 in a given environment.
| Attributes | |
|---|---|
idstring |
The ID of the bucket, which is of the form :regionName/:bucketName. |
namestring |
The name of the bucket. |
regionstring |
The region the bucket exists in. |
createdstring |
The date the bucket was created. |
urlstring |
The full endpoint URL used to make API calls on the bucket. |
Retrieve a Bucket
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/aws/test-env/buckets/us-east-1/bucket-nsturk-lullp"
The above command returns a JSON structured like this:
{
"data": {
"size": 123123,
"keyCount": 4,
"id": "us-east-1/bucket-nsturk-lullp",
"name": "bucket-nsturk-lullp",
"region": "us-east-1",
"created": "Tue Mar 22 16:15:03 UTC 2022",
"url": "https://bucket-nsturk-lullp.s3.us-east-1.amazonaws.com/",
"access": "private"
}
}
GET /services/:service_code/:environment_name/buckets/:regionName/:bucketName
Retrieve details of a given bucket.
| Attributes | |
|---|---|
idstring |
The ID of the bucket, which is of the form :regionName/:bucketName. |
namestring |
The name of the bucket. |
regionstring |
The region the bucket exists in. |
createdstring |
The date the bucket was created. |
urlstring |
The full endpoint URL used to make API calls on the bucket. |
sizeinteger |
The size of the bucket in bytes. Omitted if query parameter details=false. |
keyCountinteger |
The number of objects inside the bucket. Omitted if query parameter details=false. |
| Optional Query Parameters | |
|---|---|
details boolean |
Whether to include more details about the bucket, if omitted defaults to true and returns extra parameters size and keyCount. |
Create Bucket
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/aws/test-env/buckets"
Request body examples:
{
"access": "private",
"name": "bucket-root-agejo",
"region": "us-east-1",
}
The above command returns a JSON structured like this:
{
"taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
"taskStatus": "SUCCESS"
}
POST /services/:service_code/:environment_name/buckets?operation=create
Create a bucket in Amazon S3.
| Required | |
|---|---|
access string |
The desired access level of the bucket. The list of supported Canned ACL is: private, public-read, public-read-write, authenticated-read, log-delivery-write, aws-exec-read. |
name string |
The name of the bucket. |
region string |
The region to create the bucket in. |
| Attributes | |
|---|---|
taskId string |
The task ID related to the bucket creation. |
taskStatus string |
The status of the operation. |
Update Bucket Permissions
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/aws/test-env/buckets/:regionName/:bucketName?operation=edit_privileges"
Request body examples:
{
"access": "public-read"
}
The above command returns a JSON structured like this:
{
"taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/buckets/:regionName/:bucketName?operation=edit_privileges
Update the canned ACL of a bucket from Amazon S3.
| Required | |
|---|---|
accessstring |
The name of the Canned ACL to be assigned to the bucket. The list of supported Canned ACL is: private, public-read, public-read-write, authenticated-read, log-delivery-write, aws-exec-read. |
| Attributes | |
|---|---|
taskId string |
The task ID related to the bucket creation. |
taskStatus string |
The status of the operation. |
Delete Bucket
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/aws/test-env/buckets/us-east-1/bucketOne"
The above command returns a JSON structured like this:
{
"taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/buckets/:regionName/:bucketName
| Attributes | |
|---|---|
taskId string |
The task ID related to the bucket deletion. |
taskStatus string |
The status of the operation. |
Objects
View and manage your objects within a bucket.
List Objects
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/aws/test-env/objects?bucketId=us-east-1/bucket-root-brdje"
The above command returns a JSON structured like this:
{
"data": [
{
"name": "cat.jpeg",
"id": "us-east-1/bucket-root-nvisf/photos/cat.jpeg",
"size": 35186,
"fullPath": "photos/cat.jpeg",
"storageClass": "STANDARD",
"lastModified": "Mon Mar 21 14:15:05 EDT 2022",
"displaySize": {
"value": "34.4",
"unitKey": "units.filesizes.KB"
},
"contentType": "image/jpeg",
"eTag": "a8b886246bccda023fbb348731c1bd05",
"isFolder": false,
"bucketName": "bucket-root-nvisf",
"region": "us-east-1",
"isVirtual": false
},
{
"name": "miami",
"id": "us-east-1/bucket-root-nvisf/photos/miami/",
"fullPath": "photos/miami/",
"contentType": "application/directory",
"eTag": "",
"isFolder": true,
"bucketName": "bucket-root-nvisf",
"region": "us-east-1",
"isVirtual": false
},
{
"name": "vegas",
"id": "us-east-1/bucket-root-nvisf/photos/vegas/",
"fullPath": "photos/vegas/",
"contentType": "application/directory",
"eTag": "",
"isFolder": true,
"bucketName": "bucket-root-nvisf",
"region": "us-east-1",
"isVirtual": false
}
],
"metadata": {
"recordCount": 3
}
}
GET /services/:service_code/:environment_name/objects?bucketId=:regionName/:bucketName
Retrieve a list of objects inside a given bucket.
| Attributes | |
|---|---|
idstring |
The ID of the object, which is of the form :regionName/:bucketName/:objectName. |
namestring |
The name of the object. |
fullPathstring |
The actual key of the object inside the bucket, which is represented as a full path. |
sizeinteger |
The size of the object in bytes. |
storageClassstring |
The type of storage class on the object. |
lastModifiedstring |
The date the object was last updated. |
displaySizestring |
The size of the object represented as an object in either KB, MB, or GB. |
contentTypestring |
The type of file. |
eTagstring |
The eTag of the object generated by S3 during initial upload. |
isFolderboolean |
Boolean denoting whether the object acts as a folder. This is always true when the fullPath attribute ends with a '/' character. |
bucketNamestring |
The name of the bucket the object exists within. |
regionstring |
The name of the region the object exists within. |
isVirtualboolean |
Boolean value denoting whether the folder is virtual. If true there exists no object named :folderName/, and the folder exists only as a part of a complete object path (:folderName/:objectName). If false, there exists a key in the bucket named ‘{folderName}/’. If the query parameter nested = true, the request will not return any virtual folders. |
| Required Query Parameters | |
|---|---|
bucketIdstring |
The ID of the bucket of the form :regionName/:bucketName. |
| Optional Query Paramaters | |
|---|---|
prefixstring |
The path of the objects to search in. If prefix is left blank, it will search for objects in the root. If nested = true and prefix is left blank, it will obtain all objects in the bucket. |
nestedboolean |
Whether to include nested objects or just include objects in the root of the prefix. If nested = true, the request will not return any virtual folders. |
Retrieve an Object
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/aws/test-env/objects/us-east-1/bucket-nsturk-lullp/photos/miami.png"
The above command returns a JSON structured like this:
{
"data": {
"name": "miami.png",
"id": "us-east-1/bucket-nsturk-lullp/photos/miami.png",
"size": 35186,
"fullPath": "photos/miami.png",
"storageClass": "STANDARD",
"lastModified": "Mon Mar 21 14:15:05 EDT 2022",
"displaySize": {
"value": "34.4",
"unitKey": "units.filesizes.KB"
},
"contentType": "image/png",
"eTag": "a8b886246bccda023fbb348731c1bd05",
"isFolder": false,
"bucketName": "bucket-nsturk-lullp",
"region": "us-east-1",
"isVirtual": false
}
}
GET /services/:service_code/:environment_name/objects/:regionName/:bucketName/:pathToObject
Retrieve details of a specific object inside a given folder inside a given bucket.
| Attributes | |
|---|---|
idstring |
The ID of the object, which is of the form :regionName/:bucketName/:objectName. |
namestring |
The name of the object. |
fullPathstring |
The actual key of the object inside the bucket, which is represented as a full path. |
sizeinteger |
The size of the object in bytes. |
storageClassstring |
The type of storage class on the object. |
lastModifiedstring |
The date the object was last updated. |
displaySizestring |
The size of the object represented as an object in either KB, MB, or GB. |
contentTypestring |
The type of file. |
eTagstring |
The eTag of the object generated by S3 during initial upload. |
isFolderboolean |
Boolean value denoting whether the object acts as a folder. This is always true when the fullPath attribute ends with a '/' character. |
bucketNamestring |
The name of the bucket the object exists within. |
regionstring |
The name of the region the object exists within. |
isVirtualboolean |
Boolean value denoting whether the folder is virtual. If true there exists no object named :folderName/, and the folder exists only as a part of a complete object path (:folderName/:objectName). If false, there exists a key in the bucket named ‘{folderName}/’. If the query parameter nested = true, the request will not return any virtual folders. |
Upload Object
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/operation/upload" \
--form operation=upload \
--form entityType=objects \
--form serviceConnectionId=connection_id \
--form environmentId=environment_id \
--form filename=file_size \
--form bucketName=bucket_name \
--form regionName=region_name \
--form file=path_to_file
Request body examples as Multipart Form:
operation: upload
entityType: objects
serviceConnectionId: connection_id
environmentId: environment_id
filename: file_size
bucketName: bucket_name
regionName: region_name
file: path_to_file
The above command returns a JSON structured like this:
{
"files": [
{
"name": "filename.png",
"size": 93240,
"status": "success"
}
]
}
POST /rest/services/operations/upload
Upload a file to a bucket in Amazon S3.
| Required | |
|---|---|
operationstring |
The type of operation to execute, in this case upload. |
entityTypestring |
The entityType, in this case objects. |
serviceConnectionIdstring |
The ID tied to the related service connection. |
environmentIdstring |
The ID tied to the related environment. |
bucketNamestring |
The name of the bucket to upload the file to. |
regionNamestring |
The name of the region to upload the file to. |
:fileNamelong |
Key should be the name of the file and value should be the size of the file in bytes. |
filestring |
The path to the file. This must be the last parameter in the form. |
| Attributes | |
|---|---|
namestring |
The name of the file uploaded. |
sizeinteger |
The size of the file uploaded. |
statusstring |
String indicating the status of the operation. |
Download Object
curl --request GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/operations/:service_connection_id/download?bucketName=akc-buck®ionName=us-east-1&id=us-east-1/akc-buck/api123.png&entityType=objects&operation=download&environmentId=97430433-875c-4ba5-8c57-90a051a52729"
GET rest/services/operations/:service_connection_id/download?id=:regionName/:bucketName/:objectPath&entityType=objects&operation=download&environmentId:environmentId
Download an object from a bucket in Amazon S3.
The above command returns the binary of the file downloaded.
| Required Query Parameters | |
|---|---|
idstring |
The ID of the object to download, which is of the form ":regionName/:bucketName/:objectName". |
entityTypestring |
The type of entity to download. In this case objects. |
environmentIdstring |
The ID of environment which owns the object. |
Delete Object
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/aws/test-env/objects/:regionName/:bucketName/:pathToObject/?operation=delete"
Request body examples:
{
"id": "ap-south-1/bucket-root-dwyak/images/",
}
The above command returns a JSON structured like this:
{
"taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/objects/:regionName/:bucketName/:fullPath
Delete an object from a bucket in Amazon S3.
| Attributes | |
|---|---|
taskId string |
The task ID related to the object deletion. |
taskStatus string |
The status of the operation. |
Rename Object
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/aws/test-env/objects/:regionName/:bucketName/:pathToObject/?operation=rename"
Rename an object in a bucket in Amazon S3.
Request body examples:
{
"name": "newFilePath.png",
}
The above command returns a JSON structured like this:
{
"taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
"taskStatus": "PENDING"
}
POST /services/operation/rename :service_code/:environment_name/objects/:regionName/:bucketName/:fullPath?&operation=rename
| Required | |
|---|---|
name string |
The new name of the object. |
| Attributes | |
|---|---|
taskId string |
The task ID related to the object renaming. |
taskStatus string |
The status of the operation. |
Add Folder
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/aws/test-env/objects/?bucketName=bucketOne®ionName=regionOne&operation=add_folder"
Add a folder in amazon S3.
Request body examples:
{
"name": "newFolderName",
}
The above command returns a JSON structured like this:
{
"taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
"taskStatus": "PENDING"
}
POST /services/operation/rename :service_code/:environment_name/objects/?bucketName=:bucketName®ionName=:regionName&operation=add_folder
| Required | |
|---|---|
name string |
The name of the folder. Can contain '/' characters to create nested folders. |
| Attributes | |
|---|---|
taskId string |
The task ID related to the folder creation. |
taskStatus string |
The status of the operation. |
| Required Query Parameters | |
|---|---|
bucketName string |
The name of the bucket to create the folder in. |
regionName string |
The name of the region the bucket exists in. |
| Optional Query Parameters | |
|---|---|
prefix string |
The folder path to create the folder in. If omitted, a folder will be created in the root of the bucket. |
Rename Folder
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/aws/test-env/objects/:regionName/:bucketName/:pathToObject?&operation=rename_folder"
Renames a folder in Amazon S3. This operation renames all objects inside the folder to use the new folder name and their full path. To accomplish this, all objects must first be copied with a new key, then deleted. This operation can take an extended amount of time depending on the amount and size of objects inside the folder.
Request body examples:
{
"name": "newFolderName",
}
The above command returns a JSON structured like this:
{
"taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/objects/:regionName/:bucketName/:folderFullPath?&operation=rename_folder
| Required | |
|---|---|
name string |
The new name of the folder. Can contain '/' characters to create nested folders. |
| Attributes | |
|---|---|
taskId string |
The task ID related to the folder renaming. |
taskStatus string |
The status of the operation. |
Generate URL
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/aws/test-env/objects/:regionName/:bucketName/:pathToObject?&operation=generate_url"
Generates a presigned URL in S3. Must specify a limit in the request which denotes the amount of time (in minutes) until the URL expires. Minimum is 1 minute and maximum is 10080 minutes.
Request body examples:
{
"limit": "60",
}
The above command returns a JSON structured like this:
{
"taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
"taskStatus": "SUCCESS"
}
POST /services/:service_code/:environment_name/objects/:regionName/:bucketName/:objectFullPath?&operation=generate_url
| Required | |
|---|---|
limit integer |
The length (in minutes) the link will be active for. |
| Attributes | |
|---|---|
taskId string |
The task ID related to the URL generation. |
taskStatus string |
The status of the operation. |
Networking
Virtual Private Clouds
View and manage vpcs.
List VPCs
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-env/vpcs"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "vpc-0fc6135adfbe4a69c",
"name": "vpc-0fc6135adfbe4a69c",
"ownerId": "187065266101",
"instanceTenancy": "default",
"cidrBlock": "172.31.0.0/16",
"dhcpOptionsId": "dopt-04a202f0ccfc4ecb2",
"state": "available",
"isDefault": true
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/vpcs
Retrieve a list of all vpcs in a given environment.
| Attributes | |
|---|---|
idstring |
The ID of the VPC. |
namestring |
The name of the VPC. |
ownerIdstring |
Amazon account id of organization owner. |
instanceTenancystring |
The tenancy options for instances launched into the VPC (default, dedicated, host), set as shared by default. |
cidrBlockstring |
IPv4 network range for the VPC in CIDR notation. |
dhcpOptionsIdstring |
The DHCP options set applied to the network configuration of the VPC. |
statestring |
The state of VPC access (pending, available). |
isDefaultboolean |
Whether or not the VPC is the default environment VPC. |
Retrieve a VPC
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-env/vpcs/vpc_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "vpc-0fc6135adfbe4a69c",
"name": "vpc-0fc6135adfbe4a69c",
"ownerId": "187065266101",
"instanceTenancy": "default",
"cidrBlock": "172.31.0.0/16",
"dhcpOptionsId": "dopt-04a202f0ccfc4ecb2",
"state": "available",
"isDefault": true
}
}
GET /services/:service_code/:environment_name/vpcs/:id
Retrieve a vpc in a given environment.
| Attributes | |
|---|---|
idstring |
The ID of the VPC. |
namestring |
The name of the VPC. |
ownerIdstring |
Amazon account id of organization owner. |
instanceTenancystring |
The tenancy options for instances launched into the VPC (default, dedicated, host), set as shared by default. |
cidrBlockstring |
IPv4 network range for the VPC in CIDR notation. |
dhcpOptionsIdstring |
The DHCP options set applied to the network configuration of the VPC. |
statestring |
The state of VPC access (pending, available). |
isDefaultboolean |
Whether or not the VPC is the default environment VPC. |
Create a VPC
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-env/vpcs"
Request body example for a named VPC:
{
"name": "name-of-the-vpc",
"cidrBlock": "10.0.0.0/24"
}
The above commands return a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
GET /services/:service_code/:environment_name/vpcs
Create a VPC in a given environment.
| Attributes | |
|---|---|
idstring |
The ID of the VPC. |
| Optional | |
|---|---|
namestring |
The VPC name. A default name will be created if there isn't one provided. |
Delete a VPC
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-env/vpcs/vpc-05a6af2e6a6360915"
The above commands return a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/vpcs/:id
Delete a VPC in a given environment.
| Attributes | |
|---|---|
taskId string |
The task id related to the VPC deletion. |
taskStatus string |
The status of the operation. |
The following entities will also be deleted in the following order.
| Entities | |
|---|---|
Nodegroups |
The nodegroups of kubernetes clusters that are associated with the VPC. |
Clusters |
The kubernetes clusters with subnets that are associated with the VPC. |
Instances |
The instances that are associated with the VPC. |
Subnets |
The subnets that are associated with the VPC. |
Internet gateways |
The internet gateways that are associated with the VPC. |
Route tables |
The route tables that are associated with the VPC. |
Security groups |
The security groups that are associated with the VPC. |
Subnetworks
Subnets are a range of IP addresses within your VPC. You can use a public subnet for resources that that will be connected to the internet, and a private subnet for resources that won't be. The CIDR block of a subnet can be the same as the CIDR block for the VPC (for a single subnet in the VPC), or a subset of the CIDR block for the VPC (to create multiple subnets in the VPC). The allowed block size is between a /28 netmask and /16 netmask. If you create more than one subnet in a VPC, the CIDR blocks of the subnets cannot overlap. Each subnet must be associated with a route table, which specifies the allowed routes for outbound traffic leaving the subnet. Every subnet that you create is automatically associated with the main route table for the VPC.
List Subnets
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-env/subnetworks"
The above command returns a JSON structured like this:
{
"data": [
{
"name": "subnet-0b9cd03ba220cff0c",
"id": "subnet-0b9cd03ba220cff0c",
"cidrBlock": "172.31.32.0/20",
"availabilityZone": "us-east-1c",
"defaultSubnet": true,
"state": "available",
"subnetARN": "arn:aws:ec2:us-east-1:559465017721:subnet/subnet-0b9cd03ba220cff0c",
"routeTableId": "rtb-0ffdc3e3c20fb0246",
"availabilityZoneId": "use1-az6",
"resourceNameDNSARecordEnabled": false,
"dns64Enabled": false,
"autoAssignIPv4Address": true,
"autoAssignCustomerOwnedIPv4Address": false,
"ipv4CIDRReservations": false,
"availableIPv4Addresses": 4091,
"vpcId": "vpc-040e8c412dc149b2a"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/subnetworks
Retrieve a list of all subnets in a given environment.
| Attributes | |
|---|---|
namestring |
The name of the subnet. (ID if not set) |
idstring |
The id of the subnet. |
cidrBlockstring |
IPv4 network range for the subnet in CIDR. |
availabilityZonestring |
The availability zone of the subnet. |
defaultSubnetboolean |
If the subnet is the default for its availability zone. |
statestring |
State of the subnet. (pending, availabile) |
subnetARNstring |
The Amazon Resource Name (ARN) of the subnet. |
routeTableIdstring |
ID of the route table associated with the subnet. |
availabilityZoneIdstring |
The ID of the subnet's availability zone. |
resourceNameDNSARecordEnabledboolean |
Indicates whether to respond to DNS queries for instance hostnames with DNS A records. |
dns64Enabledboolean |
Indicates if DNS queries made to the resolver in this subnet should return synthetic IPv6 addresses for IPv4-only destinations. |
autoAssignIPv4Addressboolean |
Indicates whether instances launched in this subnet receive a public IPv4 address. |
autoAssignCustomerOwnedIPv4Addressboolean |
Indicates whether a network interface created in this subnet receives a customer-owned IPv4 address. |
ipv4CIDRReservationsboolean |
Indicates whether the subnet has IPv4 CIDR reservations. |
availableIPv4Addresesint |
The number of available addresses in the subnet's CIDR block. |
vpcIdstring |
The ID of the VPC the subnet is associated with. |
Retrieve a Subnet
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-env/subnetwork/subnet_id"
The above command returns a JSON structured like this:
{
"data": {
"name": "subnet-0b9cd03ba220cff0c",
"id": "subnet-0b9cd03ba220cff0c",
"cidrBlock": "172.31.32.0/20",
"availabilityZone": "us-east-1c",
"defaultSubnet": true,
"state": "available",
"subnetARN": "arn:aws:ec2:us-east-1:559465017721:subnet/subnet-0b9cd03ba220cff0c",
"routeTableId": "rtb-0ffdc3e3c20fb0246",
"availabilityZoneId": "use1-az6",
"resourceNameDNSARecordEnabled": false,
"dns64Enabled": false,
"autoAssignIPv4Address": true,
"autoAssignCustomerOwnedIPv4Address": false,
"ipv4CIDRReservations": false,
"availableIPv4Addresses": 4091,
"vpcId": "vpc-040e8c412dc149b2a"
}
}
GET /services/:service_code/:environment_name/subnetworks/:id
Retrieve a subnetwork in a given environment.
| Attributes | |
|---|---|
namestring |
The name of the subnet. (ID if not set) |
idstring |
The id of the subnet. |
cidrBlockstring |
IPv4 network range for the subnet in CIDR. |
availabilityZonestring |
The availability zone of the subnet. |
defaultSubnetboolean |
If the subnet is the default for its availability zone. |
statestring |
State of the subnet. (pending, availabile) |
subnetARNstring |
The Amazon Resource Name (ARN) of the subnet. |
routeTableIdstring |
ID of the route table associated with the subnet. |
availabilityZoneIdstring |
The ID of the subnet's availability zone. |
resourceNameDNSARecordEnabledboolean |
Indicates whether to respond to DNS queries for instance hostnames with DNS A records. |
dns64Enabledboolean |
Indicates if DNS queries made to the resolver in this subnet should return synthetic IPv6 addresses for IPv4-only destinations. |
autoAssignIPv4Addressboolean |
Indicates whether instances launched in this subnet receive a public IPv4 address. |
autoAssignCustomerOwnedIPv4Addressboolean |
Indicates whether a network interface created in this subnet receives a customer-owned IPv4 address. |
ipv4CIDRReservationsboolean |
Indicates whether the subnet has IPv4 CIDR reservations. |
availableIPv4Addresesint |
The number of available addresses in the subnet's CIDR block. |
vpcIdstring |
The ID of the VPC the subnet is associated with. |
Create Subnetworks
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-env/subnetworks"
Request body example for named subnets:
{
"vpcId": "vpc-0d5f70bd6b3bf9013",
"subnetsToCreate": [
{
"name": "newSubnet1",
"cidrBlock": "10.0.0.0/25",
"availabilityZone": "us-east-1c"
},
{
"name": "newSubnet2",
"cidrBlock": "10.0.0.128/25",
"availabilityZone": "us-east-1c"
}
]
}
The above commands return a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/subnetworks
Create a subnetwork in a given environment.
| Attributes | |
|---|---|
vpcIdstring |
The ID of the VPC. |
subnetsToCreateArray |
List of subnets to be created for a VPC |
cidrBlockstring |
IPv4 network range for the subnet in CIDR notation. |
| Optional | |
|---|---|
namestring |
The subnet name. A default name will be created if there isn't one provided. |
availabilityZonestring |
Availability zone of the subnet |
Delete a Subnetwork
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-env/subnetworks/subnet-07baec16047092451"
The above commands return a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/subnetworks/:id
Delete a Subnetwork in a given environment.
| Attributes | |
|---|---|
taskId string |
The task id related to the subnet deletion. |
taskStatus string |
The status of the operation. |
The following entities will also be deleted in the following order.
| Entities | |
|---|---|
Nodegroups |
The nodegroups of kubernetes clusters that are associated with the subnet. |
Clusters |
The kubernetes clusters that are associated with the subnet. |
Instances |
The instances that are associated with the subnet. |
Network interface |
The network interfaces that are associated with the subnet. |
Internet Gateways
An internet gateway is a VPC child component that allows communication between your VPC and the internet. An internet gateway enables resources in your public subnets to connect to the internet if the resource has a public IPv4 address or an IPv6 address.
List Internet Gateways
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-env/internetgateways"
The above command returns a JSON structured like this:
json { "data": [ { "id": "igw-03d0a0c6cb0d12279", "name": "my-internet-getaway", "state": "ATTACHED", "vpcId": "vpc-03326d9953f72ec19" }, { "id": "igw-06d73b330ef63d750", "name": "my-internet-gateway", "state": "ATTACHED", "vpcId": "vpc-0094a0760c22437ec" }, { "id": "igw-077302734797e7b3e", "name": "project-igw", "state": "ATTACHED", "vpcId": "vpc-0d9134bbb657cc1e3" }, { "id": "igw-09f61d7c642156d6e", "name": "igw-09f61d7c642156d6e", "state": "DETACHED" } ], "metadata": { "recordCount": 4 } }
GET /services/:service_code/:environment_name/internetgateways
| Optional Query Parameters | |
|---|---|
vpcIdstring |
Filter Internet Gateways by VPC Identifier |
Retrieve a list of all internet gateways.
| Attributes | |
|---|---|
idstring |
The ID of the Internet Gateway. |
namestring |
The name of the Internet Gateway, which is derived from a Tag with the Name key. |
statestring |
The state of the Internet Gateway depending whether or not it is attached or not to a VPC. The possible values include: ATTACHED, DETACHED. |
vpcIdstring |
The identifier of the VPC, if attached. Else this field is not returned |
Retrieve an Internet Gateway
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test/internetgateways/igw-03d0a0c6cb0d12279"
The above command returns a JSON structured like this:
{
"data": {
"id": "igw-03d0a0c6cb0d12279",
"name": "my-internet-getaway",
"state": "ATTACHED",
"vpcId": "vpc-03326d9953f72ec19"
}
}
GET /services/:service_code/:environment_name/internetgateways/:id
Retrieve an internet gateway in a given environment.
| Attributes | |
|---|---|
idstring |
The ID of the Internet Gateway. |
namestring |
The name of the Internet Gateway, which is derived from a Tag with the Name key. |
statestring |
The state of the Internet Gateway depending whether or not it is attached or not to a VPC. The possible values include: ATTACHED, DETACHED. |
vpcIdstring |
The identifier of the VPC, if attached. Else this field is not returned. |
Create an Internet Gateway
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/aws-tesv/internetgateways?operation=create"
Request body example to create an internet gateway:
{
"name": "igw-root-guthc",
"vpcId": "vpc-0094a0760c22437ec"
}
The above commands return a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/internetgateways
Create a new internet gateway in a DETACHED state in a given environment.
| Optional | |
|---|---|
namestring |
The name of the internet gateway. Automatically generated if not provided. |
vpcIdstring |
The ID of the VPC. |
Attach an Internet Gateway
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/aws-tesv/internetgateways/igw-09adee4bafdef2c31?operation=attach"
Request body example to attach an internet gateway:
{
"vpcId": "vpc-0094a0760c22437ec",
"cidrBlock": "0.0.0.0/0"
}
The above commands return a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/internetgateways/:id
Attach an internet gateway to a VPC in a given environment.
| Required | |
|---|---|
vpcIdstring |
The ID of the VPC. |
cidrBlockstring |
The CIDR IPv4 Block for the route of the Internet Gateway. |
Detach an Internet Gateway
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/aws-tesv/internetgateways/igw-09adee4bafdef2c31?operation=detach"
Request body example to detach an internet gateway:
{
"vpcId": "vpc-0ebb01212fbb562a3",
"deleteRoutes": true
}
The above commands return a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/internetgateways/:id
Detach an internet gateway from a VPC in a given environment.
| Required | |
|---|---|
vpcIdstring |
The ID of the VPC. |
deleteRoutesboolean |
Whether or not to delete the routes attached to the Internet Gateway. Default to true. |
Delete an Internet Gateway
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/aws-tesv/internetgateways/igw-00b5e5bb6cce152cb?operation=delete"
The above commands return a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/internetgateways/:id?operation=delete
Delete an internet gateway in a given environment.
| Attributes | |
|---|---|
taskId string |
The task ID for the delete route operation. |
taskStatus string |
The status of the operation. |
Routes
A route table contains a set of rules, called routes, that determine where network traffic from a gateway is directed. A route within a route table for a subnet specifies a destination and a target.
The destination for the route is represented by a IPV4 CIDR block (e.g: 0.0.0.0/0, which represents all IPv4 addresses). The target is the internet gateway that's attached to your VPC.
Create Route
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-env/routes"
Request body example for an instance with custom security group:
{
"cidrBlock": "0.0.0.0/0",
"routeTableId": "rtb-0c43fead9b67edc8b"
}
The above commands return a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/routes
Create a new route in a route table, must have an attached internet gateway to perform the operation.
| Required | |
|---|---|
| cidrBlock | IPv4 range of the traffic you want to direct. Malformed IPv4 addresses, addresses within within AWS’s link-local address space, and CIDR blocks with invalid masks are rejected. |
| routeTableId | The ID of the route table you want to add the route to. |
CIDR blocks undergo validation and correction when creating a route, below are examples of the possible transformations. When a new route is created with a CIDR block that is the same as an existing route, the existing route is overridden.
| Input CIDR | Output CIDR | |
|---|---|---|
53.100.233.76/32 |
53.100.233.76/32 |
Properly formatted CIDRs are unchanged. |
53.100.233.76/16 |
53.100.0.0/16 |
CIDRs with less specific masks than the IP are truncated to adhere to the CIDR mask. |
53.100.233.76 |
53.100.233.76/32 |
Valid IPv4 addresses without a CIDR mask are automatically appended the most specific CIDR mask. |
00.300.01.9/32 |
Rejected | Invalid IPv4 address. |
53.100.233.76/70 |
Rejected | Invalid CIDR mask. |
169.254.169.0/22 |
Rejected | Any CIDR blocks under 169.254.169.0/22 are rejected because they are within AWS's link local address space. Overlapping blocks such as 169.254.0.0/16 are fine, but the traffic within 169.254.169.0/22 is still reserved to AWS. |
2001:db8:1234:1a00::/56 |
Rejected | IPv6 CIDR blocks, even if they are properly formatted, are not supported at this time. |
Delete a Route
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/aws-tesv/routes/0.0.0.0/0?operation=delete&routeTableId=rtb-04703a509a773f41b"
The above commands return a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/routes/:cidrBlock?operation=delete&routeTableId=:routeTableId
Delete a route defined by its IPv4 CIDR block within the provided route table in a given environment.
| Attributes | |
|---|---|
taskId string |
The task ID for the delete route operation. |
taskStatus string |
The status of the operation. |
| Required Query Parameters | |
|---|---|
routeTableId string |
The ID of the Route Table for this route. |
Availability Zones
Amazon EC2 is hosted in multiple locations world-wide. Each Region is a separate geographic area, where Availability Zones are multiple, isolated locations within each Region. The code for Availability Zone is its Region code followed by a letter identifier.
When you launch an instance, you select a Region and a virtual private cloud (VPC), and then you can either select a subnet from one of the displayed Availability Zones or leave blank for the default zone. If you distribute your instances across multiple Availability Zones and one instance fails, you can design your application so that an instance in another Availability Zone can handle requests. You can also use Elastic IP addresses to mask the failure of an instance in one Availability Zone by rapidly remapping the address to an instance in another Availability Zone.
List Availability Zones
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-env/availabilityzones"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "use1-az2",
"name": "us-east-1a",
"groupName": "us-east-1",
"networkBorderGroup": "us-east-1",
"state": "available"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/availabilityzones
Retrieve a list of all availability zones for a caller context.
| Attributes | |
|---|---|
idstring |
The ID of the Availability Zone. |
namestring |
The name of the Availability Zone. |
groupNamestring |
For Availability Zones, this is the Region name. |
networkBorderGroupstring |
A unique set of Availability Zones or Local Zones from which AWS advertises public IP addresses. |
stateboolean |
The state of the zone. This will always be available (Valid states: available, information, impaired, unavailable ) |
Retrieve an Availability Zone
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-env/availabilityzones/us-east-1a"
The above command returns a JSON structured like this:
{
"data": {
"id": "use1-az2",
"name": "us-east-1a",
"groupName": "us-east-1",
"networkBorderGroup": "us-east-1",
"state": "available"
}
}
GET /services/:service_code/:environment_name/availabilityzones/name
Retrieve a list of all availability zones for a caller context.
| Attributes | |
|---|---|
idstring |
The ID of the Availability Zone. |
namestring |
The name of the Availability Zone. |
groupNamestring |
For Availability Zones, this is the Region name. |
networkBorderGroupstring |
A unique set of Availability Zones or Local Zones from which AWS advertises public IP addresses. |
stateboolean |
The state of the zone. This will always be available (Valid states: available, information, impaired, unavailable ) |
Elastic IPs
An Elastic IP address is a static public IPv4 formatted address designed to be dynamically associated with an instance. By using an Elastic IP address, upon failure of its associated instance, the address will be remapped to a new instance within your account.
List Elastic IPs
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-env/elasticips"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "eipalloc-0d3879198406bdbd7",
"name": "eipalloc-0d3879198406bdbd7",
"associationId": "eipassoc-0c6e3aecfb15418c2",
"domain": "VPC",
"instanceId": "i-006d9b167ae39a16f",
"instanceName": "instance",
"networkBorderGroup": "us-east-1",
"networkInterfaceId": "eni-0695dc329b83787e2",
"privateIpAddress": "10.0.0.172",
"publicIp": "44.194.69.77",
"state": "ASSOCIATED"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code
/:environment_name/elasticips
Retrieve a list of all elastic ips in a given environment.
| Attributes | |
|---|---|
idstring |
The ID of the Elastic IP. |
namestring |
The name of the Elastic IP. |
associationIdstring |
The ID of the association between the Elastic IP and instance. |
domainstring |
Indicates whether this Elastic IP address is for use with instances in EC2-Classic (standard) or instances in a VPC (vpc). |
instanceIdstring |
The ID of the instance that the address is associated with (if any). |
instanceNamestring |
The name of the instance that the address is associated with (if any). |
networkBorderGroupstring |
The name of the unique set of Availability Zones, Local Zones, or Wavelength Zones from which AWS advertises IP addresses. |
networkInterfaceIdboolean |
The ID of the network interface. |
privateIpAddressboolean |
The private IP address associated with the Elastic IP address. |
publicIpboolean |
The Elastic IP address. |
stateboolean |
The attachment state of the Elastic IP. Can be either Associated or Available. |
Retrieve an Elastic IP
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-env/elasticips/elasticip_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "eipalloc-0d3879198406bdbd7",
"name": "eipalloc-0d3879198406bdbd7",
"associationId": "eipassoc-0c6e3aecfb15418c2",
"domain": "VPC",
"instanceId": "i-006d9b167ae39a16f",
"instanceName": "instance",
"networkBorderGroup": "us-east-1",
"networkInterfaceId": "eni-0695dc329b83787e2",
"privateIpAddress": "10.0.0.172",
"publicIp": "44.194.69.77",
"state": "ASSOCIATED"
}
}
GET /services/:service_code
/:environment_name/elasticips/:id
Retrieve an elastic ip in a given environment.
| Attributes | |
|---|---|
idstring |
The ID of the Elastic IP. |
namestring |
The name of the Elastic IP. |
associationIdstring |
The ID of the association between the Elastic IP and instance. |
domainstring |
Indicates whether this Elastic IP address is for use with instances in EC2-Classic (standard) or instances in a VPC (vpc). |
instanceIdstring |
The ID of the instance that the address is associated with (if any). |
instanceNamestring |
The name of the instance that the address is associated with (if any). |
networkBorderGroupstring |
The name of the unique set of Availability Zones, Local Zones, or Wavelength Zones from which AWS advertises IP addresses. |
networkInterfaceIdboolean |
The ID of the network interface. |
privateIpAddressboolean |
The private IP address associated with the Elastic IP address. |
publicIpboolean |
The Elastic IP address. |
stateboolean |
The attachment state of the Elastic IP. Can be either Associated or Available. |
Allocate an Elastic IP
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws-tesv/test/elasticips?operation=allocate"
Request body to allocate an Elastic IP:
{
"name": "eip-rbensariro-oxrgp",
"networkBorderGroup": "us-east-1",
"instanceId": "i-00b2dcf0e059a2f1e"
}
The above commands return a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/elasticips?operation=allocate
Allocate an Elastic IP to a given environment environment.
| Attributes | |
|---|---|
namestring |
The name of the Elastic IP. |
networkBorderGroupstring |
The AWS network border group of the Elastic IP.Could be a region, an availability zone, local zone or wavelength zone. |
instanceIdstring |
The ID of the instance that the newly allocated Elastic IP will be associated to. This attribute is optional. The instance needs to be in a non-terminating state and possess no public IP. |
Associate an Elastic IP
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws-tesv/test/elasticips/eipalloc-0b1822bb64a812884?operation=associate"
Request body to associate an Elastic IP:
{
"instanceId": "i-00b2dcf0e059a2f1e"
}
The above commands return a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
POST /services/:service_code
/:environment_name/elasticips/:id?operation=associate
Associate an Elastic IP to an Instance in a given environment.
| Attributes | |
|---|---|
instanceIdstring |
The ID of the Instance to associate the Elastic IP to. |
Note: A Virtual Private Cloud has to be configured on the Instance, else this operation will return an error.
Disassociate an Elastic IP
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/aws-tesv/elasticips/eipalloc-0576a190ce3b575e3?operation=disassociate"
The above commands return a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
POST /services/:service_code
/:environment_name/elasticips/:id?operation=disassociate
Disassociate an elastic IP from an Instance in a given environment.
Release an Elastic IP
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/aws-tesv/elasticips/eipalloc-0576a190ce3b575e3?operation=release"
The above commands return a JSON structured like this:
{
"taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
"taskStatus": "PENDING"
}
POST /services/:service_code
/:environment_name/elasticips/:id?operation=release
Release an elastic IP in a given environment.
Note: The release operation also disassociate the elastic IP if it is associated to an Instance.
CIDR Blocks
A Classless Inter-Domain Routing (CIDR) block has to be associated to a VPC. Therefore, you need to provide the VPC ID in order to fetch the CIDR blocks.
Get CIDR Blocks by VPC
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-env/cidrblocks?vpcId=:vpc_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "172.31.0.0/16",
"state": "ASSOCIATED",
"addressType": "IPv4"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/cidrblocks
| Required Query Parameters | |
|---|---|
vpcIdstring |
Get CIDR block by VPC identifier |
Retrieve a list of all CIDR block attached to the VPC.
| Attributes | |
|---|---|
idstring |
The CIDR Block |
statestring |
The state of the CIDR. The possible values include: ASSOCIATING, ASSOCIATED, DISASSOCIATING, DISASSOCIATED, FAILING, FAILED |
addressTypestring |
The type of Address. The possible values include: IPv4 |
CIDR Reservations
A range of allowed IPv4 addresses in a subnet.
Get CIDR Reservations by Subnet
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/v1/services/aws/test-env/cidrreservations?subnetId=:subnet_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "scr-062b86003e2a05fd1",
"cidrBlock": "10.0.1.0/24",
"reservationType": "prefix",
"subnetId": "subnet-0b66921f149046e14"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/cidrreservations
| Required Query Parameters | |
|---|---|
subnetIDstring |
Get CIDR block by Subnet identifier |
Retrieve a list of all CIDR reservations associated to the Subnet.
| Attributes | |
|---|---|
idstring |
The CIDR Reservation ID |
cidrBlockstring |
The associated CIDR block |
addressTypestring |
The address reservation type (prefix, explicit) |
Kubernetes
Clusters
List your Kubernetes clusters.
List clusters
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/aws/test-area/clusters"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "test-cluster-1",
"name": "test-cluster-1",
"status": "ACTIVE",
"endpoint": "https://2CEF4912C1CF0F97B068143243A7720B.gr7.us-east-1.eks.amazonaws.com",
"creationTimestamp": "2022-06-30 12:57:11",
"addressRange": "10.100.0.0/16",
"vpcName": "vpc-0c11473c060163620",
"subnetNames": [
"subnet-0788e84e9f74187fc",
"subnet-07fbc2fe11acae389",
"subnet-00d68e63b69ebebbc",
"subnet-06fcc57288a2df042",
"subnet-04fd0e04992598e85"
],
"totalMemory": 2.0,
"totalVcpus": 4,
"numberOfNodes": 2,
"version": "1.22",
"caCert": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUMvakNDQWVhZ0F3SUJBZ0lCQURBTkJna3Foa2lHOXcwQkFRc0ZBREFWTVJNd0VRWURWUVFERXdwcmRXSmwKY201bGRHVnpNQjRYRFRJeU1EY3hNekEwTlRBeE5Wb1hEVE15TURjeE1EQTBOVEF4TlZvd0ZURVRNQkVHQTFVRQpBeE1LYTNWaVpYSnVaWFJsY3pDQ0FTSXdEUVlKS29aSWh2Y05BUUVCQlFBRGdnRVBBRENDQVFvQ2dnRUJBTWx5CmZ5QmZhTThUZENLSzJuZ7VlK3RIVC9EZjBPL2h4SEMrUi9LUU0rL3dTckNoRTRHdGdNT1hHc2tqbCsyWjFEWSsKbnRqTVlGOXVFaS9KWVlMaHB5blhkeCtZajd9bXVFK3JoQUhvQ0Y3dzg2VXN1Z1pITkFDcmE1YzNOWkpmWUdiRApqNkVxU0l0VUhVUG5NNkdnRlkwam9DcXlmUlI0Mk9JdWVQTjlDS2UrMzJyTjY0akVsZDc1THdQS2U2RWhRdllmClUyLzcyRFFJTHMyRHJXbGpOdGZmdi9DbGxQZy85TDVMSHpWdWRXNDcxeFBOZVZnQ3hOTlFMTlRaV1J1UFc4TGcKYnFqUWUvTEc4aHlQMWt2QlhMOXpPdGs0SFMxT01jejIzMzhlRjNvRk9Db1BVSytQTDE0N0ZXNENBZWRhWmtLagpJTVRVc3Z4dW5LZk1CTEhQek0wQ0F3RUFBYU5aTUZjd0RnWURWUjBQQVFIL0JBUURBZ0trTUE4R0ExVWRFd0VCCi93UUZNQU1CQWY4d0hRWURWUjBPQkJZRUZOY25DMVhjZG5xL1RtTCs0VWhRUVZsWG5UcnVNQlVHQTFVZEVRUU8KTUF5Q0NtdDFZbVZ5Ym1WMFpYTXdEUVlKS29aSWh2Y05BUUVMQlFBRXdnRUJBRGVOWm83UkdVWTJidFRZRVdFdwplYlFsUzh2WlBZWnhkUk9TR2I1cTNYTm5MTmNDNVA2TmJkT3Zkb1BIbDkzc2dFWFcxdnhvNWErTTF0WWp5dDB2CjZobkJxcFNydWhSVTVDVWFnYVRjcWNhMURkUWlMTzhuLm1uM003dHZiZ3BRYzJzY3hIdW10MUw4Zk9SdDg3YU8KTDNyMzN0VDhmNkFlL0xRVHY1RFBWcnJ1MHFveUtDdFA0YWRmS21TNW5tNXdUT2dqSDdkRHdtR3cyTFdlbDFGYgo2MUxJVWFKZFA0dXhXN3R2UExOUXBERmNKOUwxSSsyeHE2S2h2NGlFdjJEb3ArNHlLQjd6Z3cvbVdnOFhOS1M4Clc4cElxQzhFQmY5R0ZzMVUzbFpBMFFkWEVrNjRHWXlLL0lqb0tFTlBhaVRxSVNWNG5VQm82cW5YZUxtOEtTTFYKTlR3PQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==",
"amazonResourceName": "arn:aws:eks:us-east-1:818164164244:cluster/test-cluster-1"
},{
"id": "test-cluster-2",
"name": "test-cluster-2",
"status": "ACTIVE",
"endpoint": "https://33B9E5614EA65CE64E0956176B0571D3.gr7.us-east-1.eks.amazonaws.com",
"creationTimestamp": "2022-06-30 12:57:54",
"addressRange": "10.100.0.0/16",
"vpcName": "vpc-0c11473c060163620",
"subnetNames": [
"subnet-0788e84e9f74187fc",
"subnet-06fcc57288a2df042",
"subnet-04fd0e04992598e85"
],
"totalMemory": 0.5,
"totalVcpus": 1,
"numberOfNodes": 1,
"version": "1.22",
"caCert": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUMvakNDQWVhZ0F3SUJBZ0lCQURBTkJna3Foa2lHOXcwQkFRc0ZBREFWTVJNd0VRWURWUVFERXdwcmRXSmwKY201bGRHVnpNQjRYRFRJeU1EY3hNekEwTlRFeE1Wb1hEVE15TURjeE1EQTBOVEV4TVZvd0ZURVRNQkVHQTFVRQpBeE1LYTNWaVpYSnVaWFJsY3pDQ0FTSXdEUVlKS29aSWh2Y05BUUVCQlFBRGdnRVBBRENRQVFvQ2dnRUJBS3ZlCjA0QmhlZDUyWXFPTWgrVGRuQVpPVVZUaTlPblVPbmFKVlJDYzgrSUh2NUhUaFZwRUFXWktpQjByM3R4ckQ0UDUKWnh2UXVZVDR6c2NodXgxN0VDYWU4RnkrVFhnYjJQN1RNYW9TOXFLb2VyNlBMUHRLNlNnb2lLNisyK3AyQTNKawpSUU4xblJwNkhWNmxXbnY0eW5lNzBzeUk5Zm94SnVWQXV1Q1k5VlJ6TlVKbExOcEF4b0ZnN0FPbStISGhKSmFVCmhRMFRjNnFBTlZHc2VVYWNHdlJXYXBJc3ZEbWRRbHRDL21CcmVjZWdnLzBzektuVTk1TndWYldYeUhGalRSVngKb24yNXEvVXVhOURVRUlseWFWekNDbTZHS2t3cFptbFJwSkFOWjJhMld5SmZjN1AwZmlsSmg5Q25yaitOcmtOVgowVnZISUdmajUwaWhlR1ExRllrQ0F3RUFBYU5aTUZjd0RnWURWUjBQQVFIL0JBUURBZ0trTUE4R0ExVWRFd0VCCi93UUZNQU1DQWY4d0hRWURWUjBPQkJZRUZBb1ViMXJxTkU5TzlqUksxSWhFMktjZUtFNWpNQlVHQTFVZEVRUU8KTUF5Q0NtdDFZbVZ5Ym1WMFpYTXdEUVlKS29aSWh2Y05BUUVMQlFBRGdnRUJBS1pLejZJNzR4WUtuWThGdVZLawpsMHBEbjY3Q08vMTB1cFZqT3lScHc4dUEjMVVFSmRxT0V6ODAvQlZEZ09reGY4bDdPRDE1WjQrTlIzb1NKeUZKCnNJN3A5S2IxYm5oVGFDMDdpQXdiS2VCc29vZlBpdEZhK01hN3M5V1pQTCtEZmwvN3VObFo4Y3c0cXE5L0tGZ3oKVVJlNXNkN2lQRHNzRy9oc05waUdzSEh4ZWNzOHNRNVlQUkx6OTF0bTQrOGlsWjlMSm1WV1c1aTlUYU03YldESAo2RUs3N1dlSGo0L3RDTHB6dW55UGNHTGs0OFdPb2VmZGJWTUp3NFpyUEdNU0FaekN4SXhFY2YwRTh3NGJlaWtvCitkbU9iSzlJVzkyZEttRFQ0ZERlMmZWdnBsWnNRNXg2Ujk1TWFJdGdadU42VGYrdlp0bEg0TWxxV1FqbVlqVSsKRUdzPQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==",
"amazonResourceName": "arn:aws:eks:us-east-1:818164164244:cluster/test-cluster-2"
}
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/clusters
| Attributes | |
|---|---|
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
endpointstring |
The IP address of the cluster's master node. All interactions with the Kubernetes API are done through the master node. |
status string |
The status of the cluster. |
vpcName string |
The name of the VPC associated with this cluster. |
addressRange string |
The IP address range of the container pods in this cluster, in CIDR notation (e.g. 10.96.0.0/14). |
subnetNames List<string> |
The list of names of all subnets associated with this cluster. |
amazonResourceName string |
The Amazon Resource Name (ARN) that uniquely identifies the cluster. |
version string |
The version of Kubernetes that the cluster is using. |
id string |
The cluster is uniquely identified by its name. |
totalMemory double |
The total amount of memory across all nodes in GB in the cluster. |
totalVcpus integer |
The total amount of virtual CPUs across all nodes in the cluster. |
numberOfNodes integer |
The total number of nodes in the cluster. |
name string |
The name of the cluster. |
caCert string |
The certificate authority data for the cluster. |
Retrieve a cluster
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/aws/test-area/clusters/test-cluster-1"
The above command returns a JSON structured like this:
{
"data": {
"id": "test-cluster-1",
"name": "test-cluster-1",
"status": "ACTIVE",
"endpoint": "https://2CEF4912C1CF0F97B068143243A7720B.gr7.us-east-1.eks.amazonaws.com",
"creationTimestamp": "2022-06-30 12:57:11",
"addressRange": "10.100.0.0/16",
"vpcName": "vpc-0c11473c060163620",
"subnetNames": [
"subnet-0788e84e9f74187fc",
"subnet-07fbc2fe11acae389",
"subnet-00d68e63b69ebebbc",
"subnet-06fcc57288a2df042",
"subnet-04fd0e04992598e85"
],
"totalMemory": 2.0,
"totalVcpus": 4,
"numberOfNodes": 2,
"version": "1.22",
"caCert": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUMvakNDQWVhZ0F3SUJBZ0lCQURBTkJna3Foa2lHOXcwQkFRc0ZBREFWTVJNd0VRWURWUVFERXdwcmRXSmwKY201bGRHVnpNQjRYRFRJeU1EY3hNekEwTlRBeE5Wb1hEVE15TURjeE1EQTBOVEF4TlZvd0ZURVRNQkVHQTFVRQpBeE1LYTNWaVpYSnVaWFJsY3pDQ0FTSXdEUVlKS29aSWh2Y05BUUVCQlFBRGdnRVBBRENDQVFvQ2dnRUJBTWx5CmZ5QmZhTThUZENLSzJuZ7VlK3RIVC9EZjBPL2h4SEMrUi9LUU0rL3dTckNoRTRHdGdNT1hHc2tqbCsyWjFEWSsKbnRqTVlGOXVFaS9KWVlMaHB5blhkeCtZajd9bXVFK3JoQUhvQ0Y3dzg2VXN1Z1pITkFDcmE1YzNOWkpmWUdiRApqNkVxU0l0VUhVUG5NNkdnRlkwam9DcXlmUlI0Mk9JdWVQTjlDS2UrMzJyTjY0akVsZDc1THdQS2U2RWhRdllmClUyLzcyRFFJTHMyRHJXbGpOdGZmdi9DbGxQZy85TDVMSHpWdWRXNDcxeFBOZVZnQ3hOTlFMTlRaV1J1UFc4TGcKYnFqUWUvTEc4aHlQMWt2QlhMOXpPdGs0SFMxT01jejIzMzhlRjNvRk9Db1BVSytQTDE0N0ZXNENBZWRhWmtLagpJTVRVc3Z4dW5LZk1CTEhQek0wQ0F3RUFBYU5aTUZjd0RnWURWUjBQQVFIL0JBUURBZ0trTUE4R0ExVWRFd0VCCi93UUZNQU1CQWY4d0hRWURWUjBPQkJZRUZOY25DMVhjZG5xL1RtTCs0VWhRUVZsWG5UcnVNQlVHQTFVZEVRUU8KTUF5Q0NtdDFZbVZ5Ym1WMFpYTXdEUVlKS29aSWh2Y05BUUVMQlFBRXdnRUJBRGVOWm83UkdVWTJidFRZRVdFdwplYlFsUzh2WlBZWnhkUk9TR2I1cTNYTm5MTmNDNVA2TmJkT3Zkb1BIbDkzc2dFWFcxdnhvNWErTTF0WWp5dDB2CjZobkJxcFNydWhSVTVDVWFnYVRjcWNhMURkUWlMTzhuLm1uM003dHZiZ3BRYzJzY3hIdW10MUw4Zk9SdDg3YU8KTDNyMzN0VDhmNkFlL0xRVHY1RFBWcnJ1MHFveUtDdFA0YWRmS21TNW5tNXdUT2dqSDdkRHdtR3cyTFdlbDFGYgo2MUxJVWFKZFA0dXhXN3R2UExOUXBERmNKOUwxSSsyeHE2S2h2NGlFdjJEb3ArNHlLQjd6Z3cvbVdnOFhOS1M4Clc4cElxQzhFQmY5R0ZzMVUzbFpBMFFkWEVrNjRHWXlLL0lqb0tFTlBhaVRxSVNWNG5VQm82cW5YZUxtOEtTTFYKTlR3PQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==",
"amazonResourceName": "arn:aws:eks:us-east-1:818164164244:cluster/test-cluster-1"
}
}
GET /services/:service_code/:environment_name/clusters/:cluster_id
| Attributes | |
|---|---|
creationTimestampstring |
Creation timestamp in RFC3339 text format. |
endpointstring |
The IP address of the cluster's master node. All interactions with the Kubernetes API are done through the master node. |
status string |
The status of the cluster. |
vpcName string |
The name of the VPC associated with this cluster. |
addressRange string |
The IP address range of the container pods in this cluster, in CIDR notation (e.g. 10.96.0.0/14). |
subnetNames List<string> |
The list of names of all subnets associated with this cluster. |
amazonResourceName string |
The Amazon Resource Name (ARN) that uniquely identifies the cluster. |
version string |
The version of Kubernetes that the cluster is using. |
id string |
The cluster is uniquely identified by its name. |
totalMemory double |
The total amount of memory across all nodes in GB in the cluster. |
totalVcpus integer |
The total amount of virtual CPUs across all nodes in the cluster. |
numberOfNodes integer |
The total number of nodes in the cluster. |
name string |
The name of the cluster. |
caCert string |
The certificate authority data for the cluster. |
Create a cluster
curl -X POST \
-H "Content-Type: application/json" \
-H "MC-Api-Key: your_api_key" \
-d "request body" \
"https://cloudmc_endpoint/api/v2/services/aws-aaaa/test-env/clusters"
Request body examples:
// Create a cluster
{
"name": "my-cluster",
"version": "1.22",
"vpcId": "vpc-1234",
"subnetIds": ["subnet-1", "subnet-2"],
"numberOfNodes": 2,
"instanceType": "t3.medium",
"diskSize": 20
}
The above command returns a JSON structured like this:
{
"taskId": "3f045006-07db-470b-927b-6b2cfe9821af",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/clusters
Create a new cluster.
| Required | |
|---|---|
namestring |
The display name of the cluster (unique). It cannot be changed after creation. |
versionstring |
The Kubernetes version of the cluster. |
vpcIdstring |
The ID of the vpc used for the cluster resources. |
subnetIdsList |
The subnet IDs in your VPC where the control plane may place elastic network interfaces (ENIs) to facilitate communication with your cluster. |
numberOfNodes int |
Number of nodes in the primary node group for this cluster. You can resize the cluster after creation. |
instanceTypestring |
Machine type of the nodes in the default node group for this cluster. |
diskSizeint |
Size of the attached EBS volume for each node in GiB. |
Delete a cluster
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/aws/test-area/clusters/test-cluster-1"
DELETE /services/:service_code/:environment_name/clusters/:id
Delete a cluster. A cluster can only be deleted if it is in ACTIVE or FAILED state.
The above command returns a JSON structured like this:
{
"taskId":"c4e7adce-5944-410f-85e1-f74ee7ac215b",
"taskStatus":"PENDING"
}
Node groups
List node groups
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/aws/test-area/nodegroups?cluster_id=cluster-1"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "cluster-1/nodegroup-1",
"clusterName": "cluster-1",
"name": "node group-1",
"status": "ACTIVE",
"version": "1.22",
"capacityType": "ON_DEMAND",
"amiType": "AL2_x86_64",
"instanceTypes": [
"t2.nano"
],
"desiredNodeCount": 1
},
{
"id": "cluster-1/nodegroup-2",
"clusterName": "cluster-1",
"name": "node group-2",
"status": "ACTIVE",
"version": "1.22",
"capacityType": "ON_DEMAND",
"amiType": "AL2_x86_64",
"instanceTypes": [
"t2.nano"
],
"desiredNodeCount": 1
}
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/nodegroups?cluster_id=:cluster_id
| Optional | |
|---|---|
cluster_id string |
The id of the cluster in which to get the nodegroup. |
| Attributes | |
|---|---|
id string |
The node group is uniquely identified by its name. |
clusterName string |
The name of the cluster that the node group belongs to. |
name string |
The name of the node group. |
status string |
The status of the node group. |
version string |
The version of Kubernetes that the node group is using. |
capacityType string |
The capacity type that the node group will use, can either support on-demand, or spot instances. |
amiType string |
The Amazon Machine Image (AMI) type that the node group will use. |
instanceTypes List<string> |
The list of instance types that this node group's generated nodes can have. |
desiredNodeCount integer |
The total amount of virtual CPUs across all nodes in the node group. |
Retrieve a node group
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/aws/test-area/nodegroups/cluster-1/nodegroup-1"
The above command returns a JSON structured like this:
{
"data": {
"id": "cluster-1/nodegroup-1",
"clusterName": "cluster-1",
"name": "nodegroup-1",
"status": "ACTIVE",
"version": "1.22",
"capacityType": "ON_DEMAND",
"amiType": "AL2_x86_64",
"instanceTypes": [
"t2.nano"
],
"desiredNodeCount": 1
}
}
GET /services/:service_code/:environment_name/nodegroups/:id
| Attributes | |
|---|---|
id string |
The node group is uniquely identified by its name. |
clusterName string |
The name of the cluster that the node group belongs to. |
name string |
The name of the node group. |
status string |
The status of the node group. |
version string |
The version of Kubernetes that the node group is using. |
capacityType string |
The capacity type that the node group will use, can either support on-demand, or spot instances. |
amiType string |
The Amazon Machine Image (AMI) type that the node group will use. |
instanceTypes List<string> |
The list of instance types that this node group's generated nodes can have. |
desiredNodeCount integer |
The total amount of virtual CPUs across all nodes in the cluster. |
Namespaces
List namespaces
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/namespaces?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "default",
"metadata": {},
"spec": {},
"status": {}
}
],
"metadata": {
"recordCount": 4
}
}
GET /services/:service_code/:environment_name/namespaces?cluster_id=:cluster_id
Retrieve a list of all namespaces in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the namespaces. |
| Attributes | |
|---|---|
id string |
The id of the namespace. |
apiVersion string |
APIVersion defines the versioned schema of this representation of a namespace object |
metadata object |
The metadata of the namespace |
specobject |
The specification describes the attributes on a namespace. |
statusobject |
The status information of the namespace |
Get a namespace
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/namespaces/cert-manager?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "default",
"apiVersion": "v1",
"kind": "Namespace",
"metadata": {},
"spec": {},
"status": {}
}
}
GET /services/:service_code/:environment_name/namespaces/:id?cluster_id=:cluster_id
Retrieve a namespace and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the namespace. |
| Attributes | |
|---|---|
id string |
The id of the namespace. |
apiVersion string |
APIVersion defines the versioned schema of this representation of a namespace object |
metadata object |
The metadata of the namespace |
specobject |
The specification describes the attributes on a namespace. |
statusobject |
The status information of the namespace |
Create a namespace
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/namespaces?cluster_id=test-cluster"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Namespace",
"metadata": {
"name": "test-namespace"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/namespaces?cluster_id=:cluster_id
Create a namespace in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the namespace. |
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the namespace. |
metadata object |
The metadata of the namespace. |
metadata.name string |
The name of the namespace. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create namespace task. |
taskStatus string |
The status of the operation. |
Delete a namespace
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/namespaces/test-namespace?cluster_id=test-cluster"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/namespaces/:id?cluster_id=:cluster_id
Delete a namespace from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the namespace. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete namespaces task. |
taskStatus string |
The status of the operation. |
Workloads
Pods
List pods
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/pods?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "my-aerospike-0/default",
"metadata": {
"annotations": {
"checksum/config": "0e07919467cc16f2c07ac99d0036405deafa06f7d3b430215915470b3a6ca631"
},
"creationTimestamp": "2020-01-20T09:35:02.000-05:00",
"generateName": "my-aerospike-",
"labels": {
"app": "aerospike",
"controller-revision-hash": "my-aerospike-d9969496d",
"release": "my-aerospike",
"statefulset.kubernetes.io/pod-name": "my-aerospike-0"
},
"name": "my-aerospike-0",
"namespace": "default",
"ownerReferences": [
{
"apiVersion": "apps/v1",
"blockOwnerDeletion": true,
"controller": true,
"kind": "StatefulSet",
"name": "my-aerospike",
"uid": "0b00ea3d-3b92-11ea-935e-025000000001"
}
],
"resourceVersion": "95058",
"selfLink": "/api/v2/namespaces/default/pods/my-aerospike-0",
"uid": "0b055519-3b92-11ea-935e-025000000001"
},
"spec": {
"containers": [
{
"image": "aerospike/aerospike-server:4.5.0.5",
"imagePullPolicy": "IfNotPresent",
"name": "my-aerospike",
"ports": [
{
"containerPort": 3000,
"name": "clients",
"protocol": "TCP"
},
{
"containerPort": 3002,
"name": "mesh",
"protocol": "TCP"
},
{
"containerPort": 3003,
"name": "info",
"protocol": "TCP"
}
],
"readinessProbe": {
"failureThreshold": 3,
"initialDelaySeconds": 15,
"periodSeconds": 10,
"successThreshold": 1,
"tcpSocket": {
"port": 3000
},
"timeoutSeconds": 1
},
"resources": {},
"terminationMessagePath": "/dev/termination-log",
"terminationMessagePolicy": "File",
"volumeMounts": [
{
"mountPath": "/etc/aerospike",
"name": "config-volume"
},
{
"mountPath": "/var/run/secrets/kubernetes.io/serviceaccount",
"name": "default-token-64jnc",
"readOnly": true
}
]
}
],
"dnsPolicy": "ClusterFirst",
"enableServiceLinks": true,
"hostname": "my-aerospike-0",
"nodeName": "docker-desktop",
"priority": 0,
"restartPolicy": "Always",
"schedulerName": "default-scheduler",
"securityContext": {},
"serviceAccount": "default",
"serviceAccountName": "default",
"subdomain": "my-aerospike",
"terminationGracePeriodSeconds": 30,
"tolerations": [
{
"effect": "NoExecute",
"key": "node.kubernetes.io/not-ready",
"operator": "Exists",
"tolerationSeconds": 300
},
{
"effect": "NoExecute",
"key": "node.kubernetes.io/unreachable",
"operator": "Exists",
"tolerationSeconds": 300
}
],
"volumes": [
{
"configMap": {
"defaultMode": 420,
"items": [
{
"key": "aerospike.conf",
"path": "aerospike.conf"
}
],
"name": "my-aerospike"
},
"name": "config-volume"
},
{
"name": "default-token-64jnc",
"secret": {
"defaultMode": 420,
"secretName": "default-token-64jnc"
}
}
]
},
"status": {
"conditions": [
{
"lastTransitionTime": "2020-01-20T09:35:02.000-05:00",
"status": "True",
"type": "Initialized"
},
{
"lastTransitionTime": "2020-01-21T15:05:33.000-05:00",
"status": "True",
"type": "Ready"
},
{
"lastTransitionTime": "2020-01-21T15:05:33.000-05:00",
"status": "True",
"type": "ContainersReady"
},
{
"lastTransitionTime": "2020-01-20T09:35:02.000-05:00",
"status": "True",
"type": "PodScheduled"
}
],
"containerStatuses": [
{
"containerID": "docker://b45436d2978cb8e6186b22c24d3b819cabd00921a009b30c2599a935d0c69b49",
"image": "aerospike/aerospike-server:4.5.0.5",
"imageID": "docker-pullable://aerospike/aerospike-server@sha256:5bec98d46c8a521003e1c5b6f015713f2663384dd66916cca696e4e1c142c539",
"lastState": {
"terminated": {
"containerID": "docker://5e4b23c07269669f302c7c6a446399e59d553cf1a622094c1d3cc64b6f65a9e0",
"exitCode": 255,
"finishedAt": "2020-01-21T15:04:35.000-05:00",
"reason": "Error",
"startedAt": "2020-01-20T10:28:19.000-05:00"
}
},
"name": "my-aerospike",
"ready": true,
"restartCount": 2,
"state": {
"running": {
"startedAt": "2020-01-21T15:05:16.000-05:00"
}
}
}
],
"hostIP": "192.168.65.3",
"phase": "Running",
"podIP": "10.1.0.129",
"qosClass": "BestEffort",
"startTime": "2020-01-20T09:35:02.000-05:00"
}
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/pods?cluster_id=:cluster_id
Retrieve a list of all pods in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the pods. |
| Attributes | |
|---|---|
id string |
The id of the pod. |
metadata object |
The metadata of the pod. |
metadata.annotations map |
The annotations of the pod. |
metadata.creationTimestamp string |
The date of creation of the pod as a string. |
metadata.labels map |
The labels associated to the pod. |
metadata.name string |
The name of the pod. |
metadata.namespace string |
The namespace in which the pod is created. |
metadata.uid object |
The UUID of the pod. |
specobject |
The specification used to create and run the pod. |
spec.containerstring |
The name of the container running. |
statusobject |
The status information of the pod. |
status.phasestring |
The status of the pod. Possible statuses are Running, Pending, Succeeded, Unknown and Failed. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a pod
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/pods/my-aerospike-0/default?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "my-aerospike-0/default",
"metadata": {
"annotations": {
"checksum/config": "0e07919467cc16f2c07ac99d0036405deafa06f7d3b430215915470b3a6ca631"
},
"creationTimestamp": "2020-01-20T09:35:02.000-05:00",
"generateName": "my-aerospike-",
"labels": {
"app": "aerospike",
"controller-revision-hash": "my-aerospike-d9969496d",
"release": "my-aerospike",
"statefulset.kubernetes.io/pod-name": "my-aerospike-0"
},
"name": "my-aerospike-0",
"namespace": "default",
"ownerReferences": [
{
"apiVersion": "apps/v1",
"blockOwnerDeletion": true,
"controller": true,
"kind": "StatefulSet",
"name": "my-aerospike",
"uid": "0b00ea3d-3b92-11ea-935e-025000000001"
}
],
"resourceVersion": "95058",
"selfLink": "/api/v2/namespaces/default/pods/my-aerospike-0",
"uid": "0b055519-3b92-11ea-935e-025000000001"
},
"spec": {
"containers": [
{
"image": "aerospike/aerospike-server:4.5.0.5",
"imagePullPolicy": "IfNotPresent",
"name": "my-aerospike",
"ports": [
{
"containerPort": 3000,
"name": "clients",
"protocol": "TCP"
},
{
"containerPort": 3002,
"name": "mesh",
"protocol": "TCP"
},
{
"containerPort": 3003,
"name": "info",
"protocol": "TCP"
}
],
"readinessProbe": {
"failureThreshold": 3,
"initialDelaySeconds": 15,
"periodSeconds": 10,
"successThreshold": 1,
"tcpSocket": {
"port": 3000
},
"timeoutSeconds": 1
},
"resources": {},
"terminationMessagePath": "/dev/termination-log",
"terminationMessagePolicy": "File",
"volumeMounts": [
{
"mountPath": "/etc/aerospike",
"name": "config-volume"
},
{
"mountPath": "/var/run/secrets/kubernetes.io/serviceaccount",
"name": "default-token-64jnc",
"readOnly": true
}
]
}
],
"dnsPolicy": "ClusterFirst",
"enableServiceLinks": true,
"hostname": "my-aerospike-0",
"nodeName": "docker-desktop",
"priority": 0,
"restartPolicy": "Always",
"schedulerName": "default-scheduler",
"securityContext": {},
"serviceAccount": "default",
"serviceAccountName": "default",
"subdomain": "my-aerospike",
"terminationGracePeriodSeconds": 30,
"tolerations": [
{
"effect": "NoExecute",
"key": "node.kubernetes.io/not-ready",
"operator": "Exists",
"tolerationSeconds": 300
},
{
"effect": "NoExecute",
"key": "node.kubernetes.io/unreachable",
"operator": "Exists",
"tolerationSeconds": 300
}
],
"volumes": [
{
"configMap": {
"defaultMode": 420,
"items": [
{
"key": "aerospike.conf",
"path": "aerospike.conf"
}
],
"name": "my-aerospike"
},
"name": "config-volume"
},
{
"name": "default-token-64jnc",
"secret": {
"defaultMode": 420,
"secretName": "default-token-64jnc"
}
}
]
},
"status": {
"conditions": [
{
"lastTransitionTime": "2020-01-20T09:35:02.000-05:00",
"status": "True",
"type": "Initialized"
},
{
"lastTransitionTime": "2020-01-21T15:05:33.000-05:00",
"status": "True",
"type": "Ready"
},
{
"lastTransitionTime": "2020-01-21T15:05:33.000-05:00",
"status": "True",
"type": "ContainersReady"
},
{
"lastTransitionTime": "2020-01-20T09:35:02.000-05:00",
"status": "True",
"type": "PodScheduled"
}
],
"containerStatuses": [
{
"containerID": "docker://b45436d2978cb8e6186b22c24d3b819cabd00921a009b30c2599a935d0c69b49",
"image": "aerospike/aerospike-server:4.5.0.5",
"imageID": "docker-pullable://aerospike/aerospike-server@sha256:5bec98d46c8a521003e1c5b6f015713f2663384dd66916cca696e4e1c142c539",
"lastState": {
"terminated": {
"containerID": "docker://5e4b23c07269669f302c7c6a446399e59d553cf1a622094c1d3cc64b6f65a9e0",
"exitCode": 255,
"finishedAt": "2020-01-21T15:04:35.000-05:00",
"reason": "Error",
"startedAt": "2020-01-20T10:28:19.000-05:00"
}
},
"name": "my-aerospike",
"ready": true,
"restartCount": 2,
"state": {
"running": {
"startedAt": "2020-01-21T15:05:16.000-05:00"
}
}
}
],
"hostIP": "192.168.65.3",
"phase": "Running",
"podIP": "10.1.0.129",
"qosClass": "BestEffort",
"startTime": "2020-01-20T09:35:02.000-05:00"
}
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/pods/:id?cluster_id=:cluster_id
Retrieve a pod and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the pod. |
| Attributes | |
|---|---|
id string |
The id of the pod. |
metadata object |
The metadata of the pod. |
metadata.annotations map |
The annotations of the pod. |
metadata.creationTimestamp string |
The date of creation of the pod as a string. |
metadata.labels map |
The labels associated to the pod. |
metadata.name string |
The name of the pod. |
metadata.namespace string |
The namespace in which the pod is created. |
metadata.uid object |
The UUID of the pod. |
specobject |
The specification used to create and run the pod. |
spec.containerstring |
The name of the container running. |
statusobject |
The status information of the pod. |
status.phasestring |
The status of the pod. Possible statuses are Running, Pending, Succeeded, Unknown and Failed. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a pod
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/pods"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Pod",
"metadata": {
"name": "edgar-allen-pod",
"namespace": "default"
},
"spec": {
"containers": [
{
"image": "nginx",
"name": "nginx"
}
]
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/pods
Create a pod in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the pod |
metadata object |
The metadata of the pod |
metadata.name string |
The name of the pod |
specobject |
The specification used to create and run the pod |
spec.container.imagestring |
The docker image name |
spec.container.namestring |
The (unique) name of the container specified as a DNS_LABEL |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the pod is created |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create pod task. |
taskStatus string |
The status of the operation. |
Replace a pod
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/pods/edgar-allen-pod/default"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Pod",
"metadata": {
"name": "edgar-allen-pod",
"namespace": "default"
},
"spec": {
"containers": [
{
"image": "nginx",
"name": "nginx"
}
]
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/pods/:id
Replace a pod in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the pod. |
metadata object |
The metadata of the pod. |
metadata.name string |
The name of the pod. |
specobject |
The specification used to replace and run the pod. |
spec.container.imagestring |
The docker image name. |
spec.container.namestring |
The (unique) name of the container specified as a DNS_LABEL. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the pod is replaced. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace pod task. |
taskStatus string |
The status of the operation. |
Delete a pod
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/pods/my-aerospike-0/default?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/pods/:id?cluster_id=:cluster_id
Delete a pod from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to delete the pod. |
| Attributes | |
|---|---|
taskId string |
The task id related to the delete pod task. |
taskStatus string |
The status of the operation. |
Deployments
List deployments
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/deployments?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "coredns/kube-system",
"deploymentStatus": "Progressing",
"readyRatio": "2/2",
"metadata": {},
"spec": {},
"status": {}
}
],
"metadata": {
"recordCount": 6
}
}
GET /services/:service_code/:environment_name/deployments?cluster_id=:cluster_id
Retrieve a list of all deployments in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the deployments. |
| Attributes | |
|---|---|
id string |
The id of the deployment |
metadata object |
The metadata of the deployment |
images object |
The container images within a deployment |
specobject |
The specification used to create and run the deployment |
readyRatio object |
The ready replicas to total replicas ratio of this deployment set |
deploymentStatusobject |
The status information of the deployment |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a deployment
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/deployments/coredns/kube-system?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "coredns/kube-system",
"deploymentStatus": "Progressing",
"readyRatio": "2/2",
"apiVersion": "apps/v1",
"kind": "Deployment",
"metadata": {},
"spec": {},
"status": {}
}
}
GET /services/:service_code/:environment_name/deployments/:id?cluster_id=:cluster_id
Retrieve a deployment and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the deployment. |
| Attributes | |
|---|---|
id string |
The id of the deployment |
metadata object |
The metadata of the deployment |
images object |
The container images within a deployment |
specobject |
The specification used to create and run the deployment |
readyRatio object |
The ready replicas to total replicas ratio of this deployment set |
deploymentStatusobject |
The status information of the deployment |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a deployment
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/deployments?cluster_id=a_cluster_id"
Content-Type: application/json
{
"apiVersion": "apps/v1",
"kind": "Deployment",
"metadata": {
"name": "api-test-deployment-name",
"namespace": "default"
},
"spec": {
"selector": {
"matchLabels": {
"app": "nginx"
}
},
"template": {
"metadata": {
"labels": {
"app": "nginx"
}
},
"spec": {
"containers": [
{
"name": "nginx",
"image": "nginx"
}
]
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/deployments?cluster_id=:cluster_id
Create a deployment in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the deployment. |
metadata object |
The metadata of the deployment. |
metadata.name string |
The name of the deployment. |
specobject |
The specification used to replace and run the deployment. |
spec.selectorobject |
The label query over the deployment's set of resources. |
spec.templateobject |
The data a deployment's pod should have when replaced. |
spec.specobject |
The specification used to replace and run the pod(s) within the deployment. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the deployment is replaced. |
spec.selector.matchLabelsobject |
The key value pairs retrieved by a label query from a deployment. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace deployment task. |
taskStatus string |
The status of the operation. |
Replace a deployment
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/deployments/deployment-name/default"
Content-Type: application/json
{
"apiVersion": "apps/v1",
"kind": "Deployment",
"metadata": {
"name": "deployment-name",
"namespace": "default"
},
"spec": {
"selector": {
"matchLabels": {
"app": "nginx"
}
},
"template": {
"metadata": {
"labels": {
"app": "nginx"
}
},
"spec": {
"containers": [
{
"name": "nginx",
"image": "nginx"
}
]
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/deployments/:id
Replace a deployment in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the deployment. |
metadata object |
The metadata of the deployment. |
metadata.name string |
The name of the deployment. |
specobject |
The specification used to create and run the deployment. |
spec.selectorobject |
The label query over the deployment's set of resources. |
spec.templateobject |
The data a deployment's pod should have when created. |
spec.specobject |
The specification used to create and run the pod(s) within the deployment. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the deployment is created. |
spec.selector.matchLabelsobject |
The key value pairs retrieved by a label query from a deployment. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create deployment task. |
taskStatus string |
The status of the operation. |
Delete a deployment
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/deployments/dex/auth?cluster_id=a_cluster_id?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/deployments/:id?cluster_id=:cluster_id
Delete a deployment from a given environment.
| Required Attributes | |
|---|---|
cluster_id string |
The id of the cluster in which to list the deployments. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete deployment task. |
taskStatus string |
The status of the operation. |
Daemon Sets
List daemon sets
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/daemonsets?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "kube-proxy/kube-system",
"readyRatio": "3/3",
"metadata": {},
"spec": {},
"status": {}
}
],
"metadata": {
"recordCount": 5
}
}
GET /services/:service_code/:environment_name/daemonsets?cluster_id=:cluster_id
Retrieve a list of all daemon sets in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the daemon sets. |
| Attributes | |
|---|---|
id string |
The id of the daemon set |
metadata object |
The metadata of the daemon set |
specobject |
The specification used to create and run the daemon set |
statusobject |
The status information of the daemon set |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a daemon set
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/daemonsets/test-aerospike/auth?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "kube-proxy/kube-system",
"readyRatio": "3/3",
"apiVersion": "apps/v1",
"kind": "DaemonSet",
"metadata": {},
"spec": {},
"status": {}
}
}
GET /services/:service_code/:environment_name/daemonsets/:id?cluster_id=:cluster_id
Retrieve a daemon set and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the daemon set. |
| Attributes | |
|---|---|
id string |
The id of the daemon set |
metadata object |
The metadata of the daemon set |
specobject |
The specification used to create and run the daemon set |
statusobject |
The status information of the daemon set |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a daemon set
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/daemonsets?cluster_id=a_cluster_id"
Content-Type: application/json
{
"apiVersion": "apps/v1",
"metadata": {
"name": "daemonset-name",
"namespace": "default"
},
"spec": {
"selector": {
"matchLabels": {
"name": "fluentd-elasticsearch"
}
},
"template": {
"metadata": {
"labels": {
"name": "fluentd-elasticsearch"
}
},
"spec": {
"containers": [
{
"name": "fluentd-elasticsearch",
"image": "quay.io/fluentd_elasticsearch/fluentd:v2.5.2"
}
]
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/daemonsets?cluster_id=:cluster_id
Create a daemon set in a given environment.
| Required Attributes | |
|---|---|
cluster_id string |
The id of the cluster in which to get the daemon set. |
apiVersion string |
The api version (versioned schema) of the daemon set |
metadata object |
The metadata of the daemon set |
metadata.name string |
The name of the daemon set |
specobject |
The specification used to create and run the daemon set |
spec.selectorobject |
The label query over the daemon set's resources |
spec.templateobject |
The data a daemon set's pod should have when created |
spec.specobject |
The specification used to create and run the pod(s) within the daemon set |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the daemon set is created |
spec.selector.matchLabelsobject |
The key value pairs retrieved by a label query from a daemon set |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create daemon set task. |
taskStatus string |
The status of the operation. |
Replace a daemon set
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/daemonsets/daemonset-name/default"
Content-Type: application/json
{
"apiVersion": "apps/v1",
"kind": "DaemonSet",
"metadata": {
"name": "daemonset-name",
"namespace": "default"
},
"spec": {
"selector": {
"matchLabels": {
"name": "fluentd-elasticsearch"
}
},
"template": {
"metadata": {
"labels": {
"name": "fluentd-elasticsearch"
}
},
"spec": {
"containers": [
{
"name": "fluentd-elasticsearch",
"image": "quay.io/fluentd_elasticsearch/fluentd:v2.5.2"
}
]
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/daemonsets/:id
Replace a daemon set in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the daemon set. |
metadata object |
The metadata of the daemon set. |
metadata.name string |
The name of the daemon set. |
specobject |
The specification used to replace and run the daemon set. |
spec.selectorobject |
The label query over the daemon set's resources. |
spec.templateobject |
The data a daemon set's pod should have when replaced. |
spec.specobject |
The specification used to create and run the pod(s) within the daemon set. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the daemon set is replaced. |
spec.selector.matchLabelsobject |
The key value pairs retrieved by a label query from a daemon set. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace daemon set task. |
taskStatus string |
The status of the operation. |
Delete a daemon set
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/daemonsets/nginx-ingress-controller/ingress-nginx?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/daemonsets/:id?cluster_id=:cluster_id
Delete a daemon set from a given environment.
| Required Attributes | |
|---|---|
cluster_id string |
The id of the cluster in which to get the daemon set. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete daemon set task. |
taskStatus string |
The status of the operation. |
Stateful Sets
List stateful sets
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/statefulsets?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "test-aerospike/auth",
"images": ["aerospike/aerospike-server:4.5.0.5"],
"metadata": {},
"spec": {},
"status": {}
}
],
"metadata": {
"recordCount": 4
}
}
GET /services/:service_code/:environment_name/statefulsets?cluster_id=:cluster_id
Retrieve a list of all stateful sets in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the stateful sets. |
| Attributes | |
|---|---|
id string |
The id of the stateful set |
metadata object |
The metadata of the stateful set |
specobject |
The specification used to create and run the stateful set |
statusobject |
The status information of the stateful set |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a stateful set
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/statefulsets/test-aerospike/auth?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "test-aerospike/auth",
"replicaRatio": "1 / 1",
"images": ["aerospike/aerospike-server:4.5.0.5"],
"apiVersion": "apps/v1",
"kind": "StatefulSet",
"metadata": {},
"spec": {},
"status": {}
}
}
GET /services/:service_code/:environment_name/statefulsets/:id?cluster_id=:cluster_id
Retrieve a stateful set and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the stateful set. |
| Attributes | |
|---|---|
id string |
The id of the stateful set |
metadata object |
The metadata of the stateful set |
specobject |
The specification used to create and run the stateful set |
statusobject |
The status information of the stateful set |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a stateful set
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/statefulsets?cluster_id=a_cluster_id"
Content-Type: application/json
{
"apiVersion": "apps/v1",
"kind":"StatefulSet",
"metadata": {
"name": "stateful-set-name",
"namespace": "default"
},
"spec": {
"selector": {
"matchLabels": {
"app": "nginx"
}
},
"template": {
"metadata": {
"labels": {
"app": "nginx"
}
},
"spec": {
"containers": [
{
"name": "nginx",
"image": "k8s.gcr.io/nginx-slim:0.8"
}
]
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/statefulsets?cluster_id=:cluster_id
Create a stateful set in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the stateful set |
metadata object |
The metadata of the stateful set |
metadata.name string |
The name of the stateful set |
specobject |
The specification used to create and run the stateful set |
spec.selectorobject |
The label query over the stateful set's resources |
spec.templateobject |
The data a stateful set's pod should have when created |
spec.specobject |
The specification used to create and run the pod(s) within the stateful set |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the stateful set is created |
spec.selector.matchLabelsobject |
The key value pairs retrieved by a label query from a stateful set |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create stateful set task. |
taskStatus string |
The status of the operation. |
Replace a stateful set
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/statefulsets/stateful-set-name/default"
Content-Type: application/json
{
"apiVersion": "apps/v1",
"kind": "StatefulSet",
"metadata": {
"name": "stateful-set-name",
"namespace": "default"
},
"spec": {
"selector": {
"matchLabels": {
"app": "nginx"
}
},
"template": {
"metadata": {
"labels": {
"app": "nginx"
}
},
"spec": {
"containers": [
{
"name": "nginx",
"image": "k8s.gcr.io/nginx-slim:0.8"
}
]
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/statefulsets/:id
Replace a stateful set in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the stateful set. |
metadata object |
The metadata of the stateful set. |
metadata.name string |
The name of the stateful set. |
specobject |
The specification used to replaced and run the stateful set. |
spec.selectorobject |
The label query over the stateful set's of resources. |
spec.templateobject |
The data a stateful set's pod should have when replaced. |
spec.specobject |
The specification used to replace and run the pod(s) within the stateful set. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the stateful set is replaced. |
spec.selector.matchLabelsobject |
The key value pairs retrieved by a label query from a stateful set. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace stateful set task. |
taskStatus string |
The status of the operation. |
Delete a stateful set
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/statefulsets/my-aerospike/default"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/statefulsets/:id?cluster_id=:cluster_id
Delete a stateful set from a given environment.
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete stateful set task. |
taskStatus string |
The status of the operation. |
Networking (k8s)
Services
List services
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/services?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "alaintest-aerospike/default",
"ports": ["3000/TCP", "3002/TCP"],
"type": "ClusterIP",
"metadata": {},
"spec": {},
"status": {
"loadBalancer": {}
}
},
{
"id": "alertmanager-operated/monitoring",
"ports": ["9093/TCP", "9094/TCP", "9094/UDP"],
"type": "NodePort",
"apiVersion": "v1",
"kind": "Service",
"metadata": {},
"spec": {},
"status": {
"loadBalancer": {}
}
}
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/services?cluster_id=:cluster_id
Retrieve a list of all services in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the service. |
| Attributes | |
|---|---|
id string |
The id of the service |
metadata object |
The metadata of the service |
metadata.name string |
The name of the service |
metadata.namespace string |
The namespace in which the service is created |
metadata.uid object |
The UUID of the service |
type object |
The container images within a service |
portsobject |
The list of ports that are exposed by this service |
specobject |
The attributes that a user creates on a service |
spec.selectorobject |
The keys and values corresponding to pod labels, used to determine where service traffic will be routed |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a service
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/services/test-aerospike/auth?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "test-aerospike/auth",
"ports": ["3000/TCP", "3002/TCP"],
"type": "ClusterIP",
"apiVersion": "v1",
"kind": "Service",
"metadata": {},
"spec": {},
"status": {
"loadBalancer": {}
}
}
}
GET /services/:service_code/:environment_name/services/:id?cluster_id=:cluster_id
Retrieve a service and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the service. |
| Attributes | |
|---|---|
id string |
The id of the service |
metadata object |
The metadata of the service |
metadata.name string |
The name of the service |
metadata.namespace string |
The namespace in which the service is created |
metadata.uid object |
The UUID of the service |
type object |
The container images within a service |
portsobject |
The list of ports that are exposed by this service |
specobject |
The attributes that a user creates on a service |
spec.selectorobject |
The keys and values corresponding to pod labels, used to determine where service traffic will be routed |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a service
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/services"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Service",
"metadata": {
"name": "service-name",
"namespace": "default"
},
"spec": {
"ports": [
{
"port": 3000,
"protocol": "TCP"
}
],
"type": "ClusterIP"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/services/:id?cluster_id=:cluster_id
Create a service in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the service. |
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the service. |
metadata object |
The metadata of the service. |
metadata.name string |
The name of the service. |
specobject |
The specification used to create and run the service. |
spec.selectorobject |
The label query over the service's set of resources. |
spec.portsobject |
The list of ports that are exposed by this service. |
spec.typeobject |
The type of service (ClusterIP, NodePort, ExternalName or LoadBalancer) |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the service is created. |
spec.selector.matchLabelsobject |
The key value pairs retrieved by a label query from a service. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create service task. |
taskStatus string |
The status of the operation. |
Replace a service
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/services/service-name/default?cluster_id=test-cluster"
Request body example:
{
"type": "LoadBalancer",
"ports": [
"4000/TCP"
],
"apiVersion": "v1",
"kind": "Service",
"metadata": {
"creationTimestamp": "2020-08-13T11:05:00.000-04:00",
"name": "service-name",
"namespace": "default",
"resourceVersion": "170742452",
"selfLink": "/api/v2/namespaces/default/services/service-name",
"uid": "a84c8fea-f9d9-47ab-8e58-37059e9f18bd"
},
"spec": {
"clusterIP": "10.245.44.45",
"externalTrafficPolicy": "Cluster",
"ports": [
{
"nodePort": 31167,
"port": 3000,
"protocol": "TCP",
"targetPort": 306
}
],
"sessionAffinity": "ClientIP",
"sessionAffinityConfig": {
"clientIP": {
"timeoutSeconds": 10555
}
},
"type": "LoadBalancer"
},
"status": {
"loadBalancer": {}
}
}
PUT /services/:service_code/:environment_name/services/:id?cluster_id=:cluster_id
Replace a service in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the service. |
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the service. |
metadata object |
The metadata of the service. |
metadata.name string |
The name of the service. |
specobject |
The specification used to create and run the service. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace service task. |
taskStatus string |
The status of the operation. |
Delete a service
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/services/test-service/default?cluster_id=test-cluster"
DELETE /services/:service_code/:environment_name/services/:id?cluster_id=:cluster_id
Delete a service from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the service. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete service task. |
taskStatus string |
The status of the operation. |
Ingresses V1Beta1
Ingress v1beta1 has been deprecated in this API as of 26.7.0 following the removal of support by kubernetes. Please use the ingress v1 api instead.
Ingresses V1
List ingresses V1
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/ingressesv1?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "cloudmc/cmc-stg",
"endpoint": "http://cmc.cloudmc-staging-endpoint.com",
"service": {
"port": "8080",
"name": "cloudmc"
},
"metadata": {
"annotations": {},
"creationTimestamp": "2019-07-11T10:00:18.000-04:00",
"generation": 10,
"name": "cloudmc",
"namespace": "cmc-stg",
"resourceVersion": "143213903",
"uid": "376bc4c5-a3e4-11e9-b6bd-02006e76001e"
},
"spec": {
"rules": [],
"tls": []
},
"status": {
"loadBalancer": {}
}
},
{
"id": "cm-acme-http-solver-75png/auth",
"endpoint": "http://cmc.cloudmc-staging-endpoint.com",
"service": {
"port": "8089",
"name": "cm-acme-http-solver-2x5gv"
},
"metadata": {
"annotations": {},
"creationTimestamp": "2020-06-24T11:00:49.000-04:00",
"generateName": "cm-acme-http-solver-",
"generation": 1,
"labels": {
"acme.cert-manager.io/http-domain": "1965164889",
"acme.cert-manager.io/http-token": "820448657",
"acme.cert-manager.io/http01-solver": "true"
},
"name": "cm-acme-http-solver-75png",
"namespace": "auth",
"ownerReferences": [],
"resourceVersion": "143213968",
"uid": "48720f48-f2bc-45fc-95c5-60cae8ffe11e"
},
"spec": {
"rules": []
},
"status": {
"loadBalancer": {}
}
}
]
}
GET /services/:service_code/:environment_name/ingressesv1?cluster_id=:cluster_id
Retrieve a list of all ingresses V1 in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the ingress. |
| Attributes | |
|---|---|
id string |
The id of the ingress |
endpoint string |
The endpoint of the ingress |
service object |
The service associated with the ingress |
service.port string |
The port of the service associated with the ingress |
service.name string |
The name of the service associated with the ingress |
metadata object |
The metadata of the ingress |
metadata.name string |
The name of the ingress |
metadata.namespace string |
The namespace in which the ingress is created |
metadata.labels object |
The labels associated with the ingress |
metadata.uid object |
The UUID of the ingress |
specobject |
The attributes that a user specifies for an ingress |
Note that the list is not complete, since it is referring to the kubernetes api details.
Get an ingress V1
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/ingressesv1/cloudmc/cmc-stg?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "cloudmc/cmc-stg",
"endpoint": "http://cmc.cloudmc-staging-endpoint.com",
"service": {
"port": "8080",
"name": "cloudmc"
},
"metadata": {
"annotations": {},
"creationTimestamp": "2019-07-11T10:00:18.000-04:00",
"generation": 10,
"name": "cloudmc",
"namespace": "cmc-stg",
"resourceVersion": "143213903",
"uid": "376bc4c5-a3e4-11e9-b6bd-02006e76001e"
},
"spec": {
"rules": [],
"tls": []
},
"status": {
"loadBalancer": {}
}
}
}
GET /services/:service_code/:environment_name/ingressesv1/:id?cluster_id=:cluster_id
Retrieve an ingress V1 and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the ingress. |
| Attributes | |
|---|---|
id string |
The id of the ingress |
endpoint string |
The endpoint of the ingress |
service object |
The service associated with the ingress |
service.port string |
The port of the service associated with the ingress |
service.name string |
The name of the service associated with the ingress |
metadata object |
The metadata of the ingress |
metadata.name string |
The name of the ingress |
metadata.namespace string |
The namespace in which the ingress is created |
metadata.labels object |
The labels associated with the ingress |
metadata.uid object |
The UUID of the ingress |
specobject |
The attributes that a user specifies for an ingress |
Note that the list is not complete, since it is referring to the kubernetes api details.
Create an ingress V1
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/ingressesv1"
Content-Type: application/json
{
"apiVersion": "networking.k8s.io/v1",
"kind": "Ingress",
"metadata": {
"name": "ingress-name",
"namespace": "default",
"annotations": {
"nginx.ingress.kubernetes.io/rewrite-target": "/"
}
},
"spec": {
"rules": [
{
"hostname": "endpoint.com",
"http": {
"paths": [
{
"path": "/testpath",
"pathType": "Prefix",
"backend": {
"service": {
"name": "test",
"port": {
"number": 80
}
}
}
}
]
}
}
]
}
}
POST /services/:service_code/:environment_name/ingressesv1/:id?cluster_id=:cluster_id
Create an ingress V1 in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the ingress. |
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the ingress. |
metadata object |
The metadata of the ingress. |
metadata.name string |
The name of the ingress. |
specobject |
The specification used to create and run the ingress. |
spec.rulesobject |
The list of host rules used to configure the ingress. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the ingress is created. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create ingress task. |
taskStatus string |
The status of the operation. |
Replace an ingress V1
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/ingressesv1/ingress-name/default?cluster_id=test-cluster"
Request body example:
{
"endpoint": "http://my-endpoint.com",
"service": {
"port": "6556",
"name": "test"
},
"apiVersion": "networking.k8s.io/v1",
"kind": "Ingress",
"metadata": {
"creationTimestamp": "2020-08-13T14:13:42.000-04:00",
"generation": 3,
"name": "ingress-name",
"namespace": "default",
"resourceVersion": "170302224",
"uid": "c67e6a6a-2b07-4976-8b3d-2ec9fd91ae5d"
},
"spec": {
"rules": [
{
"host": "my-endpoint.com",
"http": {
"paths": [
{
"backend": {
"service": {
"name": "test",
"port": {
"number": 6556
}
}
},
"path": "/testpath"
}
]
}
}
]
},
"status": {
"loadBalancer": {
"ingress": [
{
"hostname": "hostname-worker-01"
},
{
"hostname": "hostname-worker-02"
},
{
"hostname": "hostname-worker-03"
},
{
"hostname": "hostname-worker-04"
}
]
}
}
}
PUT /services/:service_code/:environment_name/ingressesv1/:id?cluster_id=:cluster_id
Replace an ingress V1 in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the ingress. |
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the ingress. |
metadata object |
The metadata of the ingress. |
metadata.name string |
The name of the ingress. |
specobject |
The specification used to create and run the ingress. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace ingress task. |
taskStatus string |
The status of the operation. |
Delete an ingress V1
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/ingressesv1/test-ingress/default?cluster_id=test-cluster"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/ingressesv1/:id?cluster_id=:cluster_id
Delete an ingress V1 from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the ingress. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete ingress task. |
taskStatus string |
The status of the operation. |
Configuration
Config Maps
List config maps
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/configmaps?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "coredns/kube-system",
"data": {
"Corefile": ".:53 {\n errors\n health\n kubernetes cluster.local in-addr.arpa ip6.arpa {\n pods insecure\n upstream\n fallthrough in-addr.arpa ip6.arpa\n }\n prometheus :9153\n forward . /etc/resolv.conf\n cache 30\n loop\n reload\n loadbalance\n import custom/.override\n}\nimport custom/.server\n"
},
"metadata": {}
}
],
"metadata": {
"recordCount": 4
}
}
GET /services/:service_code/:environment_name/configmaps?cluster_id=:cluster_id
Retrieve a list of all config maps in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the config maps. |
| Attributes | |
|---|---|
id string |
The id of the config map. |
apiVersion string |
The API version used to retrieve this config map. |
metadata object |
The metadata of the config map. |
Get a config map
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/configmaps/coredns/kube-system?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "coredns/kube-system",
"apiVersion": "v1",
"data": {
"Corefile": ".:53 {\n errors\n health\n kubernetes cluster.local in-addr.arpa ip6.arpa {\n pods insecure\n upstream\n fallthrough in-addr.arpa ip6.arpa\n }\n prometheus :9153\n forward . /etc/resolv.conf\n cache 30\n loop\n reload\n loadbalance\n import custom/.override\n}\nimport custom/.server\n"
},
"kind": "ConfigMap",
"metadata": {}
}
}
GET /services/:service_code/:environment_name/configmaps/:id?cluster_id=:cluster_id
Retrieve a config map and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the config map. |
| Attributes | |
|---|---|
id string |
The id of the config map. |
apiVersion string |
The API version used to retrieve this config map. |
metadata object |
The metadata of the config map. |
Create a config map
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/configmaps?cluster_id=:cluster_id"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "ConfigMap",
"metadata": {
"name": "game-demo"
},
"data": {
"player_initial_lives": "3",
"ui_properties_file_name": "user-interface.properties",
"game.properties": "enemy.types=aliens,monsters\nplayer.maximum-lives=5\n",
"user-interface.properties": "color.good=purple\ncolor.bad=yellow\nallow.textmode=true\n"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/configmaps?cluster_id=:cluster_id
Create a config map in a given environment.
| Required Attributes | |
|---|---|
cluster_id string |
The id of the cluster in which to create the config map. |
apiVersion string |
The api version (versioned schema) of the config map. |
metadata object |
The metadata of the config map. |
metadata.name string |
The name of the config map. |
dataobject |
The non-confidential data (in key-value pairs) stored in the config map. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the config map is created |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create config maps task. |
taskStatus string |
The status of the operation. |
Replace a config map
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/configmaps/game-demo/default?cluster_id=:cluster_id"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "ConfigMap",
"metadata": {
"name": "game-demo",
"namespace": "default"
},
"data": {
"player_initial_lives": "5",
"ui_properties_file_name": "user-interface.properties",
"game.properties": "enemy.types=aliens,monsters\nplayer.maximum-lives=5\n",
"user-interface.properties": "color.good=purple\ncolor.bad=yellow\nallow.textmode=true\n"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/configmaps/:id?cluster_id=:cluster_id
Replace a config map in a given environment.
| Required Attributes | |
|---|---|
cluster_id string |
The id of the cluster in which to replace the config map. |
apiVersion string |
The api version (versioned schema) of the config map. |
metadata object |
The metadata of the config map. |
metadata.name string |
The name of the config map. |
dataobject |
The non-confidential data (in key-value pairs) stored in the config map. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the config map is replaced. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace config maps task. |
taskStatus string |
The status of the operation. |
Delete a config map
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/configmaps/cert-manager-cainjector-leader-election/kube-system?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/configmaps/:id?cluster_id=:cluster_id
Delete a config map from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to delete the config map. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete config map task. |
taskStatus string |
The status of the operation. |
Secrets
List secrets
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/secrets?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "default-token-xxxmt/default",
"apiVersion": "v1",
"encodedData": {
"ca.crt": "LS0tLS...",
"namespace": "a3ViZS1zeXN0ZW0=",
"token": "ZXlKa..."
},
"kind": "Secret",
"metadata": {},
"type": "kubernetes.io/service-account-token"
}
],
"metadata": {
"recordCount": 100
}
}
GET /services/:service_code/:environment_name/secrets?cluster_id=:cluster_id
Retrieve a list of all secrets in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the secrets. |
| Attributes | |
|---|---|
id string |
The id of the secret. |
apiVersion string |
The API version used to retrieve the secret. |
encodedDataobject |
The base64 encoded data stored in the secret. |
metadata object |
The metadata of the secret. |
type string |
A string used to facilitate programmatic handling of a secret's data. |
Get a secret
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/secrets/default-token-xxxmt/default?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "default-token-xxxmt/default",
"apiVersion": "v1",
"encodedData": {
"ca.crt": "LS0tLS...",
"namespace": "a3ViZS1zeXN0ZW0=",
"token": "ZXlKa..."
},
"kind": "Secret",
"metadata": {},
"type": "kubernetes.io/service-account-token"
}
}
GET /services/:service_code/:environment_name/secrets/:id?cluster_id=:cluster_id
Retrieve a secret and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the secret. |
| Attributes | |
|---|---|
id string |
The id of the secret. |
apiVersion string |
The API version used to retrieve the secret. |
encodedDataobject |
The base64 encoded data stored in the secret. |
metadata object |
The metadata of the secret. |
type string |
A string used to facilitate programmatic handling of a secret's data. |
Create a secret
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/secrets"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Secret",
"metadata": {
"name": "mysecret"
},
"type": "Opaque",
"stringData": {
"username": "my-username",
"password": "my-password"
}
}
# OR
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/secrets?cluster_id=:cluster_id"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Secret",
"metadata": {
"name": "mysecret"
},
"type": "Opaque",
"encodedData": {
"username": "YWRtaW4=",
"password": "MWYyZDFlMmU2N2Rm"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/secrets?cluster_id=:cluster_id
Create a secret in a given environment.
| Required Attributes | |
|---|---|
cluster_id string |
The id of the cluster in which to create the secret. |
apiVersion string |
The api version (versioned schema) of the secret. |
metadata object |
The metadata of the secret. |
metadata.name string |
The name of the secret. |
One of the following two attributes is also required.
| Attributes | |
|---|---|
encodedDataobject |
The base64 encoded data stored in the secret. |
stringDataobject |
The non-base64 encoded data to be encoded when the secret is created. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the secret is created |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create secret task. |
taskStatus string |
The status of the operation. |
Replace a secret
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/secrets/my-secret/shhh"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Secret",
"metadata": {
"name": "mysecret"
},
"type": "Opaque",
"stringData": {
"username": "my-username",
"password": "my-new-password"
}
}
# OR
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/secrets?cluster_id=:cluster_id"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "Secret",
"metadata": {
"name": "mysecret",
"namespace": "shhh"
},
"type": "Opaque",
"encodedData": {
"username": "YWRtaW4=",
"password": "MWYyFZDlMmU2N2Rm"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/secrets/:id?cluster_id=:cluster_id
Replace a secret in a given environment.
| Required Attributes | |
|---|---|
cluster_id string |
The id of the cluster in which to replace the secret. |
apiVersion string |
The api version (versioned schema) of the secret. |
metadata object |
The metadata of the secret. |
metadata.name string |
The name of the secret. |
One of the following two attributes is also required.
| Attributes | |
|---|---|
encodedDataobject |
The base64 encoded data stored in the secret. |
stringDataobject |
The non-base64 encoded data to be encoded when the secret is replaced. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the secret is replaced |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace secret task. |
taskStatus string |
The status of the operation. |
Delete a secret
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/secrets/default-token-xxxmt/default?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/secrets/:id?cluster_id=:cluster_id
Delete a secret from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to delete the secret. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete secret task. |
taskStatus string |
The status of the operation. |
Storage (k8s)
Storage Classes
List storage classes
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/storageclasses?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "rook-ceph-block",
"isDefault": true,
"allowVolumeExpansion": true,
"metadata": {
"annotations": {
"storageclass.kubernetes.io/is-default-class": "true"
},
"creationTimestamp": "2020-04-20T16:08:54.000-04:00",
"name": "rook-ceph-block",
"resourceVersion": "107033002",
"selfLink": "/apis/storage.k8s.io/v1/storageclasses/rook-ceph-block",
"uid": "f289c0e6-3f20-4274-8cb8-5db8b34dece6"
},
"parameters": {
"clusterID": "rook-ceph",
"csi.storage.k8s.io/controller-expand-secret-name": "rook-csi-rbd-provisioner",
"csi.storage.k8s.io/controller-expand-secret-namespace": "rook-ceph",
"csi.storage.k8s.io/fstype": "ext4",
"csi.storage.k8s.io/node-stage-secret-name": "rook-csi-rbd-node",
"csi.storage.k8s.io/node-stage-secret-namespace": "rook-ceph",
"csi.storage.k8s.io/provisioner-secret-name": "rook-csi-rbd-provisioner",
"csi.storage.k8s.io/provisioner-secret-namespace": "rook-ceph",
"imageFeatures": "layering",
"imageFormat": "2",
"pool": "replicapool"
},
"provisioner": "rook-ceph.rbd.csi.ceph.com",
"reclaimPolicy": "Delete",
"volumeBindingMode": "Immediate"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/storageclasses?cluster_id=:cluster_id
Retrieve a list of all storage classes in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the storage classes. |
| Attributes | |
|---|---|
id string |
The id of the storage class. This is the name of the resource. |
isDefault boolean |
Whether or not the storage class is the default one. |
allowVolumeExpansion boolean |
Whether not the storage class allows for expandable volumes. |
metadata object |
The metadata of the storage class. |
parameters object |
The parameters for the storage provisioner. These are storage provisioner specific and you will likely have to read external documentation. |
provisioner string |
The provisioner for the storage class. |
reclaimPolicy string |
The default volume reclaim policy for this storage class. You have a choice between Reclaim or Delete. |
volumeBindingMode string |
The default volume binding model for this storage class. You have a choice between Immediate or WaitForFirstConsumer. |
Get a storage class
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/storageclasses/rook-ceph-block?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "rook-ceph-block",
"isDefault": true,
"allowVolumeExpansion": true,
"metadata": {
"annotations": {
"storageclass.kubernetes.io/is-default-class": "true"
},
"creationTimestamp": "2020-04-20T16:08:54.000-04:00",
"name": "rook-ceph-block",
"resourceVersion": "107033002",
"selfLink": "/apis/storage.k8s.io/v1/storageclasses/rook-ceph-block",
"uid": "f289c0e6-3f20-4274-8cb8-5db8b34dece6"
},
"parameters": {
"clusterID": "rook-ceph",
"csi.storage.k8s.io/controller-expand-secret-name": "rook-csi-rbd-provisioner",
"csi.storage.k8s.io/controller-expand-secret-namespace": "rook-ceph",
"csi.storage.k8s.io/fstype": "ext4",
"csi.storage.k8s.io/node-stage-secret-name": "rook-csi-rbd-node",
"csi.storage.k8s.io/node-stage-secret-namespace": "rook-ceph",
"csi.storage.k8s.io/provisioner-secret-name": "rook-csi-rbd-provisioner",
"csi.storage.k8s.io/provisioner-secret-namespace": "rook-ceph",
"imageFeatures": "layering",
"imageFormat": "2",
"pool": "replicapool"
},
"provisioner": "rook-ceph.rbd.csi.ceph.com",
"reclaimPolicy": "Delete",
"volumeBindingMode": "Immediate"
}
}
GET /services/:service_code/:environment_name/storageclasses/:id?cluster_id=:cluster_id
Retrieve a storage class and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the storage classes. |
| Attributes | |
|---|---|
id string |
The id of the storage class. This is the name of the resource |
isDefault boolean |
Whether or not the storage class is the default one |
allowVolumeExpansion boolean |
Whether not the storage class allows for expandable volumes. |
metadata object |
The metadata of the storage class. |
parameters object |
The parameters for the storage provisioner. These are storage provisioner specific and you will likely have to read external documentation. |
provisioner string |
The provisioner for the storage class |
reclaimPolicy string |
The default volume reclaim policy for this storage class. You have a choice between Reclaim or Delete. |
volumeBindingMode string |
The default volume binding model for this storage class. You have a choice between Immediate or WaitForFirstConsumer. |
Create a storage class
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/storageclasses?cluster_id=a_cluster_id"
Content-Type: application/json
{
"apiVersion": "storage.k8s.io/v1",
"kind": "StorageClass",
"metadata": {
"name": "local-storage-name"
},
"provisioner": "kubernetes.io/no-provisioner",
"volumeBindingMode": "WaitForFirstConsumer"
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/storageclasses?cluster_id=:cluster_id
Create a storage class in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the storage class. |
metadata object |
The metadata of the storage class. |
metadata.name string |
The name of the storage class. |
provisioner string |
The provisioner for the storage class |
volumeBindingMode string |
The default volume binding model for this storage class. You have a choice between Immediate or WaitForFirstConsumer. |
| Optional Attributes | |
|---|---|
reclaimPolicy string |
The default volume reclaim policy for this storage class. You have a choice between Reclaim or Delete. |
parameters object |
The parameters for the storage provisioner. These are storage provisioner specific and you will likely have to read external documentation. |
allowVolumeExpansion boolean |
Whether not the storage class allows for expandable volumes. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create stateful set task. |
taskStatus string |
The status of the operation. |
Replace a storage class
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/storageclasses/rook-ceph-block?cluster_id=a_cluster_id"
Content-Type: application/json
{
"apiVersion": "storage.k8s.io/v1",
"metadata": {
"name": "hostpath"
},
"provisioner": "docker.io/hostpath"
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/storageclasses/:id?cluster_id=:cluster_id
Replace a storage class in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the storage class. |
metadata object |
The metadata of the storage class. |
metadata.name string |
The name of the storage class. |
provisionerobject |
The type of provisioner. |
| Optional Attributes | |
|---|---|
reclaimPolicy string |
Dynamically provisioned PersistentVolumes of this storage class are created with this reclaimPolicy. Defaults to Delete. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace storage class task. |
taskStatus string |
The status of the operation. |
Delete a storage class
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/storageclasses/rook-ceph-block?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/storageclasses/:id?cluster_id=:cluster_id
Delete a storage class from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the storage class. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete storage class task. |
taskStatus string |
The status of the operation. |
Persistent volumes
List persistent volumes
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumes?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "pvc-05097a93-120d-45d2-aaab-0f273849fccd",
"metadata": {
"annotations": {
"pv.kubernetes.io/provisioned-by": "rook-ceph.rbd.csi.ceph.com"
},
"creationTimestamp": "2020-07-03T09:12:17.000-04:00",
"finalizers": ["kubernetes.io/pv-protection"],
"name": "pvc-05097a93-120d-45d2-aaab-0f273849fccd",
"resourceVersion": "147569183",
"selfLink": "/api/v2/persistentvolumes/pvc-05097a93-120d-45d2-aaab-0f273849fccd",
"uid": "2e20a8fb-d90c-4c39-acd8-7007f85e2d8e"
},
"spec": {
"accessModes": ["ReadWriteOnce"],
"capacity": {
"storage": "8Gi"
},
"claimRef": {
"apiVersion": "v1",
"kind": "PersistentVolumeClaim",
"name": "data-cmc-cluster-zookeeper-1",
"namespace": "cmc-kafka",
"resourceVersion": "147569124",
"uid": "05097a93-120d-45d2-aaab-0f273849fccd"
},
"csi": {
"driver": "rook-ceph.rbd.csi.ceph.com",
"fsType": "ext4",
"nodeStageSecretRef": {
"name": "rook-csi-rbd-node",
"namespace": "rook-ceph"
},
"volumeAttributes": {
"clusterID": "rook-ceph",
"imageFeatures": "layering",
"imageFormat": "2",
"pool": "replicapool",
"storage.kubernetes.io/csiProvisionerIdentity": "1593101040137-8081-rook-ceph.rbd.csi.ceph.com"
},
"volumeHandle": "0001-0009-rook-ceph-0000000000000001-d11d2a4d-bd2e-11ea-b56e-7a7db811cab1"
},
"persistentVolumeReclaimPolicy": "Delete",
"storageClassName": "rook-ceph-block",
"volumeMode": "Filesystem"
},
"status": {
"phase": "Bound"
}
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/persistentvolumes?cluster_id=:cluster_id
Retrieve a list of all persistent volumes in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the persistent volumes. |
| Attributes | |
|---|---|
id string |
The id of the persistent volume. This is the name of the resource. |
metadata object |
The metadata of the persistent volume. |
spec object |
The specification of the persistent volume. |
spec.accessModes string |
The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes). |
spec.capacity.storage string |
Storage capacity of the persistent volume. |
spec.persistentVolumeReclaimPolicy string |
One of Retain (manual reclamation), Recycle (basic scrub) or Delete (associated storage asset such as AWS EBS, GCE PD, Azure Disk, or OpenStack Cinder volume is deleted). |
spec.storageClassName string |
Storage class associated to the volume. |
spec.capacity.volumeMode string |
If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device. |
status.phase string |
Volume is in one of the following phases: Available, Bound, Released or Failed. |
Get a persistent volume
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumes/pvc-05097a93-120d-45d2?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"id": "pvc-05097a93-120d-45d2",
"metadata": {
"annotations": {
"pv.kubernetes.io/provisioned-by": "rook-ceph.rbd.csi.ceph.com"
},
"creationTimestamp": "2020-07-03T09:12:17.000-04:00",
"finalizers": ["kubernetes.io/pv-protection"],
"name": "pvc-05097a93-120d-45d2-aaab-0f273849fccd",
"resourceVersion": "147569183",
"selfLink": "/api/v2/persistentvolumes/pvc-05097a93-120d-45d2-aaab-0f273849fccd",
"uid": "2e20a8fb-d90c-4c39-acd8-7007f85e2d8e"
},
"spec": {
"accessModes": ["ReadWriteOnce"],
"capacity": {
"storage": "8Gi"
},
"claimRef": {
"apiVersion": "v1",
"kind": "PersistentVolumeClaim",
"name": "data-cmc-cluster-zookeeper-1",
"namespace": "cmc-kafka",
"resourceVersion": "147569124",
"uid": "05097a93-120d-45d2-aaab-0f273849fccd"
},
"csi": {
"driver": "rook-ceph.rbd.csi.ceph.com",
"fsType": "ext4",
"nodeStageSecretRef": {
"name": "rook-csi-rbd-node",
"namespace": "rook-ceph"
},
"volumeAttributes": {
"clusterID": "rook-ceph",
"imageFeatures": "layering",
"imageFormat": "2",
"pool": "replicapool",
"storage.kubernetes.io/csiProvisionerIdentity": "1593101040137-8081-rook-ceph.rbd.csi.ceph.com"
},
"volumeHandle": "0001-0009-rook-ceph-0000000000000001-d11d2a4d-bd2e-11ea-b56e-7a7db811cab1"
},
"persistentVolumeReclaimPolicy": "Delete",
"storageClassName": "rook-ceph-block",
"volumeMode": "Filesystem"
},
"status": {
"phase": "Bound"
}
}
GET /services/:service_code/:environment_name/persistentvolumes/:id?cluster_id=:cluster_id
Retrieve a persistent volume and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the persistent volume. |
| Attributes | |
|---|---|
id string |
The id of the persistent volume. This is the name of the resource. |
metadata object |
The metadata of the persistent volume. |
spec object |
The specification of the persistent volume. |
spec.accessModes string |
The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes). |
spec.capacity.storage string |
Storage capacity of the persistent volume. |
spec.persistentVolumeReclaimPolicy string |
One of Retain (manual reclamation), Recycle (basic scrub) or Delete (associated storage asset such as AWS EBS, GCE PD, Azure Disk, or OpenStack Cinder volume is deleted). |
spec.storageClassName string |
Storage class associated to the volume. |
spec.capacity.volumeMode string |
If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device. |
status.phase string |
Volume is in one of the following phases: Available, Bound, Released or Failed. |
Create a persistent volume
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumes"
Content-Type: application/json
{
"apiVersion": "v1",
"metadata": {
"name": "small-pvc",
"namespace": "default"
},
"spec": {
"accessModes": [
"ReadWriteOnce"
],
"resources": {
"requests": {
"storage": "10G"
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/persistentvolumes
Create a persistent volume in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the persistent volume. |
metadata object |
The metadata of the persistent volume. |
metadata.name string |
The name of the persistent volume. |
spec object |
The spec for the persistent volume. |
spec.accessModes array |
A list of access modes, the options are: ReadWriteOnce, ReadOnlyMany and ReadWriteMany. |
spec.capacity.storage string |
Measured in bytes. You can express storage as a plain integer or as a fixed-point integer using one of these suffixes: E, P, T, G, M, K. You can also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki. |
spec.<VOLUME_TYPE> object |
Volume types are identified by name and what volume types are supported differ heavily by Kubernetes deployment. The contents of the object also depend on the volume type. Examples of common volumes types are nfs, hostPath, or local. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the pod is created, if not specified will create the persistent volume in default. |
spec.storageClassName string |
Storage class associated to the volume. |
spec.claimRef array |
The name of the PersistentVolumeClaim associated to the persistent volume. |
spec.mountOptions array |
Mount options for when a Persistent Volume is mounted on a node. |
spec.nodeAffinity array |
Defines constraints that limit what nodes this volume can be accessed from. |
spec.persistentVolumeReclaimPolicy array |
One of Retain (manual reclamation), Recycle (basic scrub) or Delete (associated storage asset such as AWS EBS, GCE PD, Azure Disk, or OpenStack Cinder volume is deleted). |
spec.volumeMode array |
If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device. |
status.phase string |
Volume is in one of the following phases: Available, Bound, Released or Failed. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create persistent volume task. |
taskStatus string |
The status of the operation. |
Replace a persistent volume
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumes/my-persistent-volume?cluster_id=a_cluster_id"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "PersistentVolume",
"metadata": {
"annotations": {
"key": "value"
},
"name": "persistentvolumes-name"
},
"spec": {
"accessModes": [
"ReadWriteMany"
],
"capacity": {
"storage": "2Gi"
},
"claimRef": {
"apiVersion": "v1",
"kind": "PersistentVolumeClaim",
"name": "pv-claim-name",
"namespace": "default",
"resourceVersion": "259087",
"uid": "11957feb-1acc-4c7e-911e-f77d5d7be5ac"
},
"hostPath": {
"path": "/etc/path"
},
"persistentVolumeReclaimPolicy": "Retain",
"storageClassName": "standard",
"volumeMode": "Filesystem"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/persistentvolumes/:id?cluster_id=a_cluster_id
Replace a persistent volume in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the volume. |
metadata object |
The metadata of the volume. |
metadata.name string |
The name of the volume. |
specobject |
The specification used to replace and run the volume. |
spec.accessModesstring |
The desired access modes the volume should have. |
spec.capacity.storagestring |
The size of the claim. |
spec.hostPath.pathstring |
The path of the directory on the host. |
| Optional Attributes | |
|---|---|
metadata.annotations string |
Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. |
spec.claimRef string |
part of a bi-directional binding between PersistentVolume and PersistentVolumeClaim. Expected to be non-nil when bound. |
spec.persistentVolumeReclaimPolicy string |
What happens to a persistent volume when released from its claim. |
spec.storageClassName string |
Name of StorageClass to which this persistent volume belongs. Empty value means that this volume does not belong to any StorageClass. |
spec.volumeMode string |
Defines if a volume is intended to be used with a formatted filesystem or to remain in raw block state. Value of Filesystem is implied when not included in spec. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace volume task. |
taskStatus string |
The status of the operation. |
Delete a persistent volume
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumes/pvc-05097a93-120d-45d2?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/persistentvolumes/:id?cluster_id=:cluster_id
Delete a perstent volume from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the perstent volume. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete persistent volume task. |
taskStatus string |
The status of the operation. |
Persistent Volume Claims
List persistent volume claims
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumeclaims?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "cmc-staging-mysql/cmc-stg",
"metadata": {
"annotations": {
"pv.kubernetes.io/bind-completed": "yes",
"pv.kubernetes.io/bound-by-controller": "yes",
"volume.beta.kubernetes.io/storage-provisioner": "rook-ceph.rbd.csi.ceph.com"
},
"creationTimestamp": "2020-04-27T12:01:22.000-04:00",
"finalizers": ["kubernetes.io/pvc-protection"],
"labels": {
"app": "cmc-staging-mysql",
"chart": "mysql-0.4.5",
"heritage": "Helm",
"release": "cmc-staging"
},
"name": "cmc-staging-mysql",
"namespace": "cmc-stg",
"resourceVersion": "111495311",
"selfLink": "/api/v2/namespaces/cmc-stg/persistentvolumeclaims/cmc-staging-mysql",
"uid": "ba115a65-e3c5-4e37-8548-e37ec395e79f"
},
"spec": {
"accessModes": ["ReadWriteOnce"],
"resources": {
"requests": {
"storage": "8Gi"
}
},
"storageClassName": "rook-ceph-block",
"volumeMode": "Filesystem",
"volumeName": "pvc-ba115a65-e3c5-4e37-8548-e37ec395e79f"
},
"status": {
"accessModes": ["ReadWriteOnce"],
"capacity": {
"storage": "8Gi"
},
"phase": "Bound"
}
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/persistentvolumeclaims?cluster_id=:cluster_id
Retrieve a list of all persistent volume claims in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the persistent volume claims. |
| Attributes | |
|---|---|
id string |
The id of the persistent volume claim. This is the name and namespace of the resource. |
metadata object |
The metadata of the persistent volume claim. |
spec object |
The specification of the persistent volume claim. |
spec.accessModes string |
The requested access mode. The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes). |
spec.resources.requests.storage string |
The requested storage capacity of the persistent volume. |
spec.storageClassName string |
Storage class associated to the volume. |
spec.capacity.volumeMode string |
If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device. |
status object |
The status of the persistent volume claim. |
status.phase string |
The claim is in one of the following phases: Pending, Bound, Lost or Terminating. |
status.accessModes string |
The allocated access mode. The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes). |
status.capacity.storage string |
The allocated storage capacity. |
Get a persistent volume claim
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumeclaims/cmc-staging-mysql/cmc-stg?cluster_id=:cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "cmc-staging-mysql/cmc-stg",
"apiVersion": "v1",
"kind": "PersistentVolumeClaim",
"metadata": {
"annotations": {
"pv.kubernetes.io/bind-completed": "yes",
"pv.kubernetes.io/bound-by-controller": "yes",
"volume.beta.kubernetes.io/storage-provisioner": "rook-ceph.rbd.csi.ceph.com"
},
"creationTimestamp": "2020-04-27T12:01:22.000-04:00",
"finalizers": ["kubernetes.io/pvc-protection"],
"labels": {
"app": "cmc-staging-mysql",
"chart": "mysql-0.4.5",
"heritage": "Helm",
"release": "cmc-staging"
},
"name": "cmc-staging-mysql",
"namespace": "cmc-stg",
"resourceVersion": "111495311",
"selfLink": "/api/v2/namespaces/cmc-stg/persistentvolumeclaims/cmc-staging-mysql",
"uid": "ba115a65-e3c5-4e37-8548-e37ec395e79f"
},
"spec": {
"accessModes": ["ReadWriteOnce"],
"resources": {
"requests": {
"storage": "8Gi"
}
},
"storageClassName": "rook-ceph-block",
"volumeMode": "Filesystem",
"volumeName": "pvc-ba115a65-e3c5-4e37-8548-e37ec395e79f"
},
"status": {
"accessModes": ["ReadWriteOnce"],
"capacity": {
"storage": "8Gi"
},
"phase": "Bound"
}
}
}
GET /services/:service_code/:environment_name/persistentvolumeclaims/:id?cluster_id=:cluster_id
Retrieve a persistent volume claim and all its info in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the persistent volume claim. |
| Attributes | |
|---|---|
id string |
The id of the persistent volume claim. This is the name and namespace of the resource. |
metadata object |
The metadata of the persistent volume claim. |
spec object |
The specification of the persistent volume claim. |
spec.accessModes string |
The requested access mode. The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes). |
spec.resources.requests.storage string |
The requested storage capacity of the persistent volume. |
spec.storageClassName string |
Storage class associated to the volume. |
spec.capacity.volumeMode string |
If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device. |
status object |
The status of the persistent volume claim. |
status.phase string |
The claim is in one of the following phases: Pending, Bound, Lost or Terminating. |
status.accessModes string |
The allocated access mode. The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes). |
status.capacity.storage string |
The allocated storage capacity. |
Create a persistent volume claim
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumeclaims?cluster_id=a_cluster_id"
Content-Type: application/json
{
"apiVersion": "v1",
"kind": "PersistentVolumeClaim",
"metadata": {
"name": "small-pvc",
"namespace": "default"
},
"spec": {
"accessModes": [
"ReadWriteOnce"
],
"resources": {
"requests": {
"storage": "10G"
}
}
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/persistentvolumeclaims?cluster_id=:cluster_id
Create a persistent volume claim in a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to list the persistent volume claims. |
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the persistent volume claim. |
metadata object |
The metadata of the persistent volume claim. |
metadata.name string |
The name of the persistent volume claim. |
spec object |
The spec for the persistent volume claim. |
spec.accessModes array |
A list of access modes, the options are: ReadWriteOnce, ReadOnlyMany and ReadWriteMany. |
spec.resources.requests.storage string |
Measured in bytes. You can express storage as a plain integer or as a fixed-point integer using one of these suffixes: E, P, T, G, M, K. You can also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki. |
| Optional Attributes | |
|---|---|
metadata.namespace string |
The namespace in which the pod is created, if not specified will create the claim in default. |
spec.storageClassName string |
The storage class for the persistent volume claim, will use the default if not specified. |
spec.resources.limits object |
Limits describe the maximum number of storage resources allowed. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create persistent volume claim task. |
taskStatus string |
The status of the operation. |
Replace a persistent volume claim
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumeclaims/my-persistent-volume-claim/default?cluster_id=a_cluster_id"
Content-Type: application/json
{
"id": "pv-claim-name/default",
"apiVersion": "v1",
"kind": "PersistentVolumeClaim",
"metadata": {
"name": "pv-claim-name",
"namespace": "default"
},
"spec": {
"accessModes": [
"ReadWriteOnce"
],
"resources": {
"requests": {
"storage": "1Gi"
}
},
"storageClassName": "standard",
"volumeName": "persistentvolumes-name",
"dataSource": "dataSource"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/persistentvolumeclaims/:id?cluster_id=:cluster_id
Replace a persistent volume claim in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the claim. |
metadata object |
The metadata of the claim. |
metadata.name string |
The name of the claim. |
specobject |
The specification used to replace and run the claim. |
spec.accessModesstring |
The desired access modes the volume should have. |
spec.resources.requests.storagestring |
The size of the claim. |
spec.storageClassNamestring |
The name of the StorageClass required by the claim. |
| Optional Attributes | |
|---|---|
spec.volumeNamestring |
The binding reference to the PersistentVolume backing this claim. Only required if claim is bound. |
spec.volumemode string |
What type of volume is required by the claim. Value of Filesystem is implied when not included in claim spec. |
spec.dataSource string |
This field can be used to specify either: an existing VolumeSnapshot object, an existing PVC or an existing custom resource/object that implements data population. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace persistent volume claim task. |
taskStatus string |
The status of the operation. |
Delete a persistent volume claim
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/persistentvolumeclaims/cmc-staging-mysql/cmc-stg?cluster_id=:cluster_id"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/persistentvolumeclaims/:id?cluster_id=:cluster_id
Delete a perstent volume claim from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to get the perstent volume claim. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete persistent volume claim task. |
taskStatus string |
The status of the operation. |
Access control
Service accounts
List service accounts
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/serviceaccounts?cluster_id=:cluster_id"
The above command returns a JSON structured like this:
{
"metadata": {
"name": "vpnkit-controller",
"namespace": "kube-system",
"selfLink": "/api/v2/namespaces/kube-system/serviceaccounts/vpnkit-controller",
"uid": "b9afa8a8-3d64-4605-959f-12bb5c6cfba2",
"resourceVersion": "481",
"creationTimestamp": "2020-09-18T14:47:48Z",
"annotations": {
"kubectl.kubernetes.io/last-applied-configuration": "{\"apiVersion\":\"v1\",\"kind\":\"ServiceAccount\",\"metadata\":{\"annotations\":{},\"name\":\"vpnkit-controller\",\"namespace\":\"kube-system\"}}\n"
}
},
"secrets": [
{
"name": "vpnkit-controller-token-hl674"
}
]
}
]
}
GET /services/:service_code/:environment_name/serviceaccounts?cluster_id=:cluster_id
Retrieve a list of all service accounts in a given environment.
| Attributes | |
|---|---|
id string |
The id of the service account. |
metadata.annotations map |
The annotations of the service account. |
metadata object |
The metadata of the service account. |
metadata.creationTimestamp string |
The date of creation of the service account as a string. |
metadata.name string |
The name of the service account. |
metadata.namespace string |
The namespace in which the service account is created. |
metadata.uid object |
The UUID of the service account. |
metadata.secrets List<object> |
The secrets of the service account. |
secretsSize integer |
The number of secrets of the service account. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a service account
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/serviceaccounts/serviceaccount-name/serviceaccount-namespace?cluster_id=:cluster_id"
The above command returns a JSON structured like this:
{
"data": {
"id": "default",
"age": "1w5d",
"secretsSize": 1,
"metadata": {
"creationTimestamp": "2020-09-18T10:46:40.000-04:00",
"name": "default",
"namespace": "default",
"uid": "80a0de4d-a187-44c3-b691-1481220a5817"
},
"secrets": [
{
"name": "default-token-lrth9"
}
]
},
"fieldTransitions": {},
"operations": []
}
GET /services/:service_code/:environment_name/serviceaccounts/:id?cluster_id=:cluster_id
Retrieve a service account and all its info in a given environment.
| Attributes | |
|---|---|
id string |
The id of the service account. |
metadata object |
The metadata of the service account. |
metadata.creationTimestamp string |
The date of creation of the service account as a string. |
metadata.name string |
The name of the service account. |
metadata.namespace string |
The namespace in which the service account is created. |
metadata.uid object |
The UUID of the service account. |
metadata.secrets List<object> |
The secrets of the service account. |
secretsSize integer |
The number of secrets of the service account. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a service account
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/serviceaccounts?cluster_id=:cluster_id"
Content-Type: application/json
{
"apiVersion": "v1",
"metadata": {
"name": "service-account-name",
"namespace": "default"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/serviceaccounts?cluster_id=:cluster_id
Create a service account in a given environment.
| Required Attributes | |
|---|---|
apiVersion string |
The api version (versioned schema) of the service account. |
metadata object |
The metadata of the service account. |
metadata.name string |
The name of the service account. |
metadata.namespace string |
The namespace of the service account. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create service account task. |
taskStatus string |
The status of the operation. |
Replace a service account
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/serviceaccounts/service-account-name/namespace-name?cluster_id=:cluster_id"
Content-Type: application/json
{
"metadata": {
"name": "service-account-name",
"namespace": "namespace-name"
}
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/serviceaccounts/:id?cluster_id=:cluster_id
Replace a service account in a given environment.
| Required Attributes | |
|---|---|
metadata object |
The metadata of the service account. |
metadata.name string |
The name of the service account. |
metadata.namespace string |
The namespace of the service account. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create service account task. |
taskStatus string |
The status of the operation. |
Delete a service account
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/serviceaccounts/my-service-account/my-namespace?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/serviceaccounts/:id?cluster_id=:cluster_id
Delete a service account from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to delete the service account. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete service account task. |
taskStatus string |
The status of the operation. |
Roles
List (namespace) Roles
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/roles?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "role-id",
"age": "1w4d",
"metadata": {
"creationTimestamp": "2020-09-18T10:01:26.000-04:00",
"name": "kubeadm:bootstrap-signer-clusterinfo",
"namespace": "kube-public",
"uid": "57ef0321-e44a-43c9-9f2a-e448c3a66a46"
},
"rules": [
{
"apiGroups": [],
"resourceNames": [],
"resources": [],
"verbs": []
}
]
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/roles?cluster_id=:cluster_id
Retrieve a list of all roles in a given environment.
| Attributes | |
|---|---|
id string |
The id of the role. |
metadata object |
The metadata of the role. |
metadata.creationTimestamp string |
The date of creation of the service account as a string. |
metadata.name string |
The name of the role. |
metadata.namespace string |
The namespace in which the role is created. |
metadata.uid object |
The UUID of the role. |
rules array |
The array of rules associated with this role. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a role
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/roles/role-name/role-namespace?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
The above command returns a JSON structured like this:
{
"data": {
"id": "kubeadm:bootstrap-signer-clusterinfo",
"age": "1w4d",
"apiVersion": "rbac.authorization.k8s.io/v1",
"kind": "Role",
"metadata": {
"creationTimestamp": "2020-09-18T10:01:26.000-04:00",
"name": "kubeadm:bootstrap-signer-clusterinfo",
"namespace": "kube-public",
"uid": "57ef0321-e44a-43c9-9f2a-e448c3a66a47"
},
"rules": [
{
"apiGroups": [],
"resourceNames": [],
"resources": [],
"verbs": []
}
]
}
}
GET /services/:service_code/:environment_name/roles/:id?cluster_id=:cluster_id
Retrieve a role and all its info in a given environment.
| Attributes | |
|---|---|
id string |
The id of the role. |
apiVersion string |
The API version used to retrieve this role. |
metadata object |
The metadata of the role. |
rules array |
The array of rules associated with this role. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a role
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/roles?cluster_id=:cluster_id"
Content-Type: application/json
{
"apiVersion": "rbac.authorization.k8s.io/v1",
"kind": "Role",
"namespace": "default",
"name": "test-name",
"metadata": {
"namespace": "default",
"name": "test-name"
},
"rules": [
{
"apiGroups": [
""
],
"resources": [
"resource"
],
"verbs": [
"get",
"watch"
]
}
]
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/roles?cluster_id=:cluster_id
Create a role in a given environment.
| Attributes | |
|---|---|
id string |
The id of the role. |
apiVersion string |
The API version used to create this role. |
metadata.name string |
The name of the role. |
metadata.namespace string |
The namespace of the role. |
rules array |
The array of rules associated with this role. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create role task. |
taskStatus string |
The status of the operation. |
Replace a role
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/roles/role-name/namespace-name?cluster_id=:cluster_id"
Content-Type: application/json
{
"metadata": {
"name": "role-name",
"namespace": "namespace-name"
}
"rules": [
{
"apiGroups": [
""
],
"resources": [
"resource"
],
"verbs": [
"get",
"watch",
"..."
]
}
]
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/roles/:id?cluster_id=:cluster_id
Replace a role in a given environment.
| Required Attributes | |
|---|---|
metadata object |
The metadata of the role. |
metadata.name string |
The name of the role. |
metadata.namespace string |
The namespace of the role. |
metadata.namespace string |
The namespace of the role. |
| Optional Attributes | |
|---|---|
rules array |
The array of rules associated with this role. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace role operation. |
taskStatus string |
The status of the operation. |
Delete a role
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/roles/default-token-xxxmt/default?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/roles/:id?cluster_id=:cluster_id
Delete a role from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to delete the role. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete role task. |
taskStatus string |
The status of the operation. |
Role bindings
List (namespace) role bindings
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/rolebindings?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
The above command returns a JSON structured like this:
{
"data": {
"entity": {
"id": "kubeadm:bootstrap-signer-clusterinfo",
"age": "1w5d",
"metadata": {
"creationTimestamp": "2020-09-18T10:46:32.000-04:00",
"name": "kubeadm:bootstrap-signer-clusterinfo",
"namespace": "kube-public",
"uid": "4fcfe5b9-a1c3-4b3b-9cb6-6df4a1da945f"
},
"roleRef": {
"apiGroup": "rbac.authorization.k8s.io",
"kind": "Role",
"name": "kubeadm:bootstrap-signer-clusterinfo"
},
"subjects": [
{
"apiGroup": "rbac.authorization.k8s.io",
"kind": "User",
"name": "system:anonymous"
}
]
},
"fieldTransitions": {},
"operations": []
},
}
GET /services/:service_code/:environment_name/rolebindings?cluster_id=:cluster_id
Retrieve a list of all role bindings in a given environment.
| Attributes | |
|---|---|
id string |
The id of the role binding. |
metadata object |
The metadata of the role binding. |
metadata.creationTimestamp string |
The date of creation of the role binding as a string. |
metadata.name string |
The name of the role binding. |
metadata.namespace string |
The namespace in which the role binding is created. |
metadata.uid object |
The UUID of the role binding. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Get a role binding
curl -X GET </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/rolebindings/rolebinding-name/rolebinding-namespace?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
The above command returns a JSON structured like this:
{
"data": {
"id": "kubeadm:bootstrap-signer-clusterinfo",
"age": "1w5d",
"metadata": {
"creationTimestamp": "2020-09-18T10:46:32.000-04:00",
"name": "kubeadm:bootstrap-signer-clusterinfo",
"namespace": "kube-public",
"uid": "4fcfe5b9-a1c3-4b3b-9cb6-6df4a1da945f"
},
"roleRef": {
"apiGroup": "rbac.authorization.k8s.io",
"kind": "Role",
"name": "kubeadm:bootstrap-signer-clusterinfo"
},
"subjects": [
{
"apiGroup": "rbac.authorization.k8s.io",
"kind": "User",
"name": "system:anonymous"
}
]
},
"fieldTransitions": {},
"operations": []
},
}
GET /services/:service_code/:environment_name/rolebindings/:id?cluster_id=:cluster_id
Retrieve a role binding and all its info in a given environment.
| Attributes | |
|---|---|
id string |
The id of the role binding. |
apiVersion string |
The API version used to retrieve this role binding. |
metadata object |
The metadata of the role binding. |
roleRefobject |
The role to bind. Can reference a Role in the current namespace or a ClusterRole in the global namespace. |
subjects array |
The array of subjects associated with this role binding. |
Note that the list is not complete, since it is refering to the kubernetes api details.
Create a role binding
curl -X POST </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/rolebindings?cluster_id=:cluster_id"
Content-Type: application/json
{
"kind": "Rolebinding",
"metadata": {
"name": "rolebinding-name",
"namespace": "namespace-name"
},
"roleRef": {
"apiGroup": "rbac.authorization.k8s.io",
"kind": "Role",
"name": "role-name"
},
"subjects": [
{
"kind": "ServiceAccount",
"name": "service-account-name",
"namespace": "service-account-namespace"
},
{
"kind": "Group",
"name": "group-name",
"namespace": "group-namespace"
},
{
"kind": "User",
"name": "user-name",
}
]
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/rolebindings?cluster_id=:cluster_id
Create a role binding in a given environment.
| Required Attributes | |
|---|---|
metadata object |
The metadata of the role binding. |
metadata.name string |
The name of the role binding. |
metadata.namespace string |
The namespace of the role binding. |
roleRefobject |
The role to bind. Can reference a Role in the current namespace or a ClusterRole in the global namespace. |
subjectsarray |
Subjects hold references to the objets the role applies to. Can be users, groups, or service accounts. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the create role binding task. |
taskStatus string |
The status of the operation. |
Replace a role binding
curl -X PUT </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/rolebindings/rolebinding-name/namespace-name?cluster_id=:cluster_id"
Content-Type: application/json
{
"metadata": {
"name": "service-account-name",
"namespace": "namespace-name"
},
"roleRef": {
"apiGroup": "",
"kind": "Role",
"name": "role-name"
},
"subjects": [
{
"kind": "ServiceAccount",
"name": "default",
"namespace": "default"
},
{
"kind": "user",
"name": "user1",
}
]
}
The above command returns a JSON structured like this:
{
"taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
"taskStatus": "PENDING"
}
PUT /services/:service_code/:environment_name/rolebindings/:id?cluster_id=:cluster_id
Replace a role binding in a given environment.
| Required Attributes | |
|---|---|
metadata object |
The metadata of the role binding. |
metadata.name string |
The name of the role binding. |
metadata.namespace string |
The namespace of the role binding. |
roleRefobject |
The role to bind. Can reference a Role in the current namespace or a ClusterRole in the global namespace. |
subjectsarray |
Subjects hold references to the objets the role applies to. Can be users, groups, or service accounts. |
Return value:
| Attributes | |
|---|---|
taskId string |
The id corresponding to the replace role binding operation. |
taskStatus string |
The status of the operation. |
Delete a role binding
curl -X DELETE </span>
-H "MC-Api-Key: your_api_key" </span>
"https://cloudmc_endpoint/api/v2/services/a_service/an_environment/rolebindings/default-token-xxxmt/default?cluster_id=a_cluster_id"
The above command returns a JSON structured like this:
json { "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b", "taskStatus": "PENDING" }DELETE /services/:service_code/:environment_name/rolebindings/:id?cluster_id=:cluster_id
Delete a role binding from a given environment.
| Required | |
|---|---|
cluster_id string |
The id of the cluster in which to delete the role binding. |
| Attributes | |
|---|---|
taskId string |
The id corresponding to the delete role binding task. |
taskStatus string |
The status of the operation. |
PureStorage plugin
The PureStorage plugin allows you to operate on multiple PureStorage Flashblades at once. It exposes the management of object storage on these Flashblades.
Object Storage API Credentials
View and manage your FlashBlade's s3 object-storage API credentials. You need to be a member of the environment to operation on these resources.
List credentials
curl --request GET \
--url 'https://cloudmc_endpoint/v1/services/purestorage/test-env/apiCredentials/:regionName' \
--header 'Mc-Api-key: your_api_key'
The above command returns JSON structured like this:
{
"data": [
{
"accessKeyId": "AKIASQ3YW7O2RARDARUO",
"region": "montreal"
}
],
"metadata": {
"recordCount": 1
}
}
GET /services/:service_code/:environment_name/apiCredentials
Retrieves a list of object storage s3 API credentials. There will only ever be one entry per region, if credentials exist for that region.
| Attributes | |
|---|---|
accessKeyIdstring |
The ID for your s3 access key. |
regionstring |
The region the access key belongs to. |
Get credentials
curl --request GET \
--url 'https://cloudmc_endpoint/v1/services/purestorage/test-env/apiCredentials/:regionName' \
--header 'Mc-Api-key: your_api_key'
The above command returns a JSON structured like this:
{
"data": {
"accessKeyId": "AKIASQ3YW7O2RARDARUO",
"region": "montreal"
}
}
GET /services/:service_code/:environment_name/apiCredentials/:regionName
Retrieves an access key by region.
| Attributes | |
|---|---|
accessKeyIdstring |
The ID for your s3 access key. |
regionstring |
The region the access key belongs to. |
Generate credentials
curl --request POST \
--url 'https://cloudmc_endpoint/api/v2/services/purestorage/test-env/apiCredentials?operation=generate' \
--header 'Content-Type: application/json' \
--header 'Mc-Api-key: your_api_key' \
--data '{
"region": "montreal"
}'
The above command returns JSON structured like this:
{
"data": {
"accessKeyId": "AKIASQ3YW7O2YA4SUQEC",
"secretKey": "YOUR_SECRET_KEY",
"region": "montreal"
},
"taskId": "fa565b90-e530-4abe-b88a-8aa6adc4dfc6",
"taskStatus": "SUCCESS"
}
POST /services/:service_code/:environment_name/apiCredentials?operation=generate
Generates, or regenerates if credentials are existing, access key credentials on the purestorage environment. Regenerating will permanently delete the previous credentials saved for your user.
The secret key should be saved immediately after generation as it will be not be retrievable afterwards.
| Required | |
|---|---|
region string |
The PureStorage Flashblade you want to create the credentials on. |
Return value:
| Attributes | |
|---|---|
accessKeyIdstring |
The ID for your object storage's s3 API access key. |
secretKeystring |
The secret key for your object storage's s3 API access key. Should be saved. |
regionstring |
The region the access key belongs to. Values depend on the configuration of the PureStorage plugin. |
taskId string |
The task ID. |
taskStatus string |
The status of the operation. |
Delete credentials
curl --request DELETE \
--url `https://cloudmc_endpoint/api/v2/services/purestorage-aaaa/emcilroy-local/apiCredentials/montreal` \
--header 'Mc-Api-Key: your_api_key'
The above command returns JSON structured like this:
{
"taskId": "0773c033-8f0c-4366-bfe3-ca544b7cb3ac",
"taskStatus": "SUCCESS"
}
DELETE /services/:service_code/:environment_name/apiCredentials/:regionName
Deletes the access credentials for your purestorage environment.
Return value:
| Attributes | |
|---|---|
taskId string |
The task ID. |
taskStatus string |
The status of the operation. |
Buckets
View and manage your buckets.
List Buckets
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/purestorage/test-env/buckets"
The above command returns a JSON structured like this:
{
"data": [
{
"id": "ap-south-1/bucketOne",
"name": "bucketOne",
"region": "ap-south-1",
"created": "Tue Mar 01 16:13:29 EST 2022",
"url": "http://10.23.42.55/bucketOne/",
"access": "private"
},
{
"id": "us-east-1/bucketTwo",
"name": "bucketTwo",
"region": "us-east-1",
"created": "Fri Mar 04 16:20:29 EST 2022",
"url": "http://10.23.42.65/bucketTwo/",
"access": "private"
}
],
"metadata": {
"recordCount": 2
}
}
GET /services/:service_code/:environment_name/buckets
Retrieve a list of all buckets in a given environment.
| Attributes | |
|---|---|
idstring |
The ID of the bucket, which is of the form :regionName/:bucketName. |
namestring |
The name of the bucket. |
regionstring |
The region the bucket exists in. |
createdstring |
The date the bucket was created. |
urlstring |
The full endpoint URL used to make API calls on the bucket. |
accessstring |
The access level of the bucket. |
Retrieve a Bucket
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/purestorage/test-env/buckets/us-east-1/bucketOne"
The above command returns a JSON structured like this:
{
"data": {
"size": 28807002,
"keyCount": 2,
"displaySize": {
"value": "27.5",
"unitKey": "units.filesizes.MB"
},
"id": "us-east-1/bucketOne",
"name": "bucketOne",
"region": "us-east-1",
"created": "Tue Mar 22 16:15:03 UTC 2022",
"url": "http://10.23.42.55/bucketOne",
"access": "private"
}
}
GET /services/:service_code/:environment_name/buckets/:regionName/:bucketName
Retrieve details of a given bucket.
| Attributes | |
|---|---|
idstring |
The ID of the bucket, which is of the form :regionName/:bucketName. |
namestring |
The name of the bucket. |
regionstring |
The region the bucket exists in. |
createdstring |
The date the bucket was created. |
urlstring |
The full endpoint URL used to make API calls on the bucket. |
accessstring |
The access level of the bucket. |
sizeinteger |
The size of the bucket in bytes. Omitted if query parameter details=false. |
keyCountinteger |
The number of objects inside the bucket. Omitted if query parameter details=false. |
displaySizestring |
The size of the bucket represented as an object in either KB, MB, or GB. |
| Optional Query Parameters | |
|---|---|
details boolean |
Whether to include more details about the bucket, if omitted defaults to true and returns extra parameters size and keyCount. |
Create Bucket
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/purestorage/test-env/buckets"
Request body examples:
{
"access": "private",
"name": "bucket-root-agejo",
"region": "us-east-1",
}
The above command returns a JSON structured like this:
{
"taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
"taskStatus": "SUCCESS"
}
POST /services/:service_code/:environment_name/buckets?operation=create
Create a bucket in a given region.
| Required | |
|---|---|
access string |
The desired access level of the bucket. The list of supported Canned ACL is: private, public-read, public-read-write, authenticated-read, log-delivery-write, aws-exec-read. |
name string |
The name of the bucket. |
region string |
The region to create the bucket in. |
| Attributes | |
|---|---|
taskId string |
The task id related to the bucket creation. |
taskStatus string |
The status of the operation. |
Delete Bucket
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/purestorage/test-env/buckets/us-east-1/bucketOne"
The above command returns a JSON structured like this:
{
"taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/buckets/:regionName/:bucketName
| Attributes | |
|---|---|
taskId string |
The task id related to the bucket deletion. |
taskStatus string |
The status of the operation. |
Objects
View and manage your objects within a bucket.
List Objects
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/purestorage/test-env/objects?bucketId=us-east-1/bucket-root-brdje"
The above command returns a JSON structured like this:
{
"data": [
{
"name": "text.rtf",
"id": "us-east-1/bucket-root-brdje/text.rtf",
"size": 14403501,
"fullPath": "text.rtf",
"storageClass": "STANDARD",
"lastModified": "Fri May 06 09:09:15 EDT 2022",
"displaySize": {
"value": "13.7",
"unitKey": "units.filesizes.MB"
},
"contentType": "application/rtf",
"eTag": "4bdf0a5e8c871d520f835b2fc519f263",
"bucketName": "bucket-root-brdje",
"region": "us-east-1",
"containingFolder": "",
"isFolder": false,
"isVirtual": false
},
{
"name": "photos",
"id": "us-east-1/bucket-root-brdje/photos/",
"fullPath": "photos/",
"contentType": "application/directory",
"eTag": "",
"bucketName": "bucket-root-brdje",
"region": "us-east-1",
"containingFolder": "",
"isFolder": true,
"isVirtual": true
}
],
"metadata": {
"recordCount": 3
}
}
GET /services/:service_code/:environment_name/objects?bucketId=:regionName/:bucketName
Retrieve a list of objects inside a given bucket.
| Attributes | |
|---|---|
namestring |
The name of the object. |
idstring |
The ID of the object, which is of the form :regionName/:bucketName/:objectName. |
sizeinteger |
The size of the object in bytes. |
fullPathstring |
The actual key of the object inside the bucket, which is represented as a full path. |
storageClassstring |
The type of storage class on the object. |
lastModifiedstring |
The date the object was last updated. |
displaySizestring |
The size of the object represented as an object in either KB, MB, or GB. |
contentTypestring |
The type of file. |
eTagstring |
The eTag of the object generated by S3 during initial upload. |
bucketNamestring |
The name of the bucket the object exists within. |
regionstring |
The name of the region the object exists within. |
containingFolderstring |
The folder containing the object. An empty string is returned if the object is not contained within a folder in the bucket. |
isFolderboolean |
Boolean denoting whether the object acts as a folder. This is always true when the fullPath attribute ends with a '/' character. |
isVirtualboolean |
Boolean value denoting whether the folder is virtual. If true there exists no object named :folderName/, and the folder exists only as a part of a complete object path (:folderName/:objectName). If false, there exists a key in the bucket named ‘{folderName}/’. If the query parameter nested = true, the request will not return any virtual folders. |
| Required Query Parameters | |
|---|---|
bucketIdstring |
The ID of the bucket of the form :regionName/:bucketName. |
| Optional Query Paramaters | |
|---|---|
prefixstring |
The path of the objects to search in. If prefix is left blank, it will search for objects in the root. If nested = true and prefix is left blank, it will obtain all objects in the bucket. |
nestedboolean |
Whether to include nested objects or just include objects in the root of the prefix. If nested = true, the request will not return any virtual folders. Defaults to false. |
Retrieve an Object
curl -X GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/purestorage/test-env/objects/us-east-1/bucket-root-brdje/photos/miami.png"
The above command returns a JSON structured like this:
{
"data": {
"name": "miami.png",
"id": "us-east-1/bucket-root-brdje/photos/miami.png",
"size": 35186,
"fullPath": "photos/miami.png",
"storageClass": "STANDARD",
"lastModified": "Mon Mar 21 14:15:05 EDT 2022",
"displaySize": {
"value": "34.4",
"unitKey": "units.filesizes.KB"
},
"contentType": "image/png",
"eTag": "a8b886246bccda023fbb348731c1bd05",
"isFolder": false,
"bucketName": "bucket-root-brdje",
"region": "us-east-1",
"isVirtual": false
}
}
GET /services/:service_code/:environment_name/objects/:regionName/:bucketName/:pathToObject
Retrieve a list of objects inside a given folder inside a given bucket.
| Attributes | |
|---|---|
idstring |
The ID of the object, which is of the form :regionName/:bucketName/:objectName. |
namestring |
The name of the object. |
fullPathstring |
The actual key of the object inside the bucket, which is represented as a full path. |
sizeinteger |
The size of the object in bytes. |
storageClassstring |
The type of storage class on the object. |
lastModifiedstring |
The date the object was last updated. |
displaySizestring |
The size of the object represented as an object in either KB, MB, or GB. |
contentTypestring |
The type of file. |
eTagstring |
The eTag of the object generated by S3 during initial upload. |
isFolderboolean |
Boolean value denoting whether the object acts as a folder. This is always true when the fullPath attribute ends with a '/' character. |
bucketNamestring |
The name of the bucket the object exists within. |
regionstring |
The name of the region the object exists within. |
isVirtualboolean |
Boolean value denoting whether the folder is virtual. If true there exists no object named :folderName/, and the folder exists only as a part of a complete object path (:folderName/:objectName). If false, there exists a key in the bucket named ‘{folderName}/’. If the query parameter nested = true, the request will not return any virtual folders. |
Upload Object
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/purestorage/operation/upload" \
--form operation=upload \
--form entityType=objects \
--form serviceConnectionId=connection_id \
--form environmentId=environment_id \
--form filename=file_size \
--form bucketName=bucket_name \
--form regionName=region_name \
--form file=path_to_file
Request body examples as Multipart Form:
operation: upload
entityType: objects
serviceConnectionId: connection_id
environmentId: environment_id
filename: file_size
bucketName: bucket_name
regionName: region_name
file: path_to_file
The above command returns a JSON structured like this:
{
"files": [
{
"name": "filename.png",
"size": 93240,
"status": "success"
}
]
}
POST /rest/services/operations/upload
Upload a file to a bucket.
| Required | |
|---|---|
operationstring |
The type of operation to execute, in this case upload. |
entityTypestring |
The entityType, in this case objects. |
serviceConnectionIdstring |
The ID tied to the related service connection. |
environmentIdstring |
The ID tied to the related environment. |
bucketNamestring |
The name of the bucket to upload the file to. |
regionNamestring |
The name of the region to upload the file to. |
:fileNamelong |
Key should be the name of the file and value should be the size of the file in bytes. |
filestring |
The path to the file. This must be the last parameter in the form. |
| Attributes | |
|---|---|
namestring |
The name of the file uploaded. |
sizeinteger |
The size of the file uploaded. |
statusstring |
String indicating the status of the operation. |
Download Object
curl --request GET \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/operations/:service_connection_id/download?bucketName=akc-buck®ionName=us-east-1&id=us-east-1/akc-buck/api123.png&entityType=objects&operation=download&environmentId=97430433-875c-4ba5-8c57-90a051a52729"
GET rest/services/operations/:service_connection_id/download?id=:regionName/:bucketName/:objectPath&entityType=objects&operation=download&environmentId:environmentId
Download an object from a bucket.
The above command returns the binary of the file downloaded.
| Required Query Parameters | |
|---|---|
idstring |
The ID of the object to download, which is of the form ":regionName/:bucketName/:objectName". |
entityTypestring |
The type of entity to download. In this case objects. |
environmentIdstring |
The ID of environment which owns the object. |
Delete Object
curl -X DELETE \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/purestorage/test-env/objects/:regionName/:bucketName/:pathToObject/?operation=delete"
Request body examples:
{
"id": "ap-south-1/bucket-root-dwyak/images/",
}
The above command returns a JSON structured like this:
{
"taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
"taskStatus": "PENDING"
}
DELETE /services/:service_code/:environment_name/objects/:regionName/:bucketName/:fullPath
Delete an object from a bucket.
| Attributes | |
|---|---|
taskId string |
The task ID related to the object deletion. |
taskStatus string |
The status of the operation. |
Rename Object
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/purestorage/test-env/objects/:regionName/:bucketName/:pathToObject/?operation=rename"
Rename an object in a bucket.
Request body examples:
{
"name": "newFilePath.png",
}
The above command returns a JSON structured like this:
{
"taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
"taskStatus": "PENDING"
}
POST /services/operation/rename :service_code/:environment_name/objects/:regionName/:bucketName/:fullPath?&operation=rename
| Required | |
|---|---|
name string |
The new name of the object. |
| Attributes | |
|---|---|
taskId string |
The task ID related to the object renaming. |
taskStatus string |
The status of the operation. |
Add Folder
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/purestorage/test-env/objects/?bucketName=bucketOne®ionName=regionOne&operation=add_folder"
Add a folder to a bucket.
Request body examples:
{
"name": "newFolderName",
}
The above command returns a JSON structured like this:
{
"taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
"taskStatus": "PENDING"
}
POST /services/operation/rename :service_code/:environment_name/objects/?bucketName=:bucketName®ionName=:regionName&operation=add_folder
| Required | |
|---|---|
name string |
The name of the folder. Can contain '/' characters to create nested folders. |
| Attributes | |
|---|---|
taskId string |
The task ID related to the folder creation. |
taskStatus string |
The status of the operation. |
| Required Query Parameters | |
|---|---|
bucketName string |
The name of the bucket to create the folder in. |
regionName string |
The name of the region the bucket exists in. |
| Optional Query Parameters | |
|---|---|
prefix string |
The folder path to create the folder in. If omitted, a folder will be created in the root of the bucket. |
Rename Folder
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/purestorage/test-env/objects/:regionName/:bucketName/:pathToObject?&operation=rename_folder"
Renames a folder in a bucket. This operation renames all objects inside the folder to use the new folder name and their full path. To accomplish this, all objects must first be copied with a new key, then deleted. This operation can take an extended amount of time depending on the amount and size of objects inside the folder.
Request body examples:
{
"name": "newFolderName",
}
The above command returns a JSON structured like this:
{
"taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
"taskStatus": "PENDING"
}
POST /services/:service_code/:environment_name/objects/:regionName/:bucketName/:folderFullPath?&operation=rename_folder
| Required | |
|---|---|
name string |
The new name of the folder. Can contain '/' characters to create nested folders. |
| Attributes | |
|---|---|
taskId string |
The task ID related to the folder renaming. |
taskStatus string |
The status of the operation. |
Generate URL
curl -X POST \
-H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v2/services/purestorage/test-env/objects/:regionName/:bucketName/:pathToObject?&operation=generate_url"
Generates a presigned URL. Must specify a limit in the request which denotes the amount of time (in minutes) until the URL expires. Minimum is 1 minute and maximum is 10080 minutes.
Request body examples:
{
"limit": "60",
}
The above command returns a JSON structured like this:
{
"taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
"taskStatus": "SUCCESS"
}
POST /services/:service_code/:environment_name/objects/:regionName/:bucketName/:objectFullPath?&operation=generate_url
| Required | |
|---|---|
limit integer |
The length (in minutes) the link will be active for. |
| Attributes | |
|---|---|
taskId string |
The task ID related to the URL generation. |
taskStatus string |
The status of the operation. |